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.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.
When calling our API, include the URL to the API service for the corresponding environment:
Payment Options API is an API responsible for listing all shops and their respective payment options available for a specific merchant
userType required | string user type must be either "regular" or "guest" |
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) |
merchantIdentifier required | string The email of the merchant. |
Success response if the merchant is active, if not, data list will be empty
Bad Request: The request was unacceptable, due to missing required parameter
Unauthorized: Missing or invalid apiKey provided
HTTP method not supported
Something went wrong while communicating with the server
Sandbox URL
Production Url
{- "merchantIdentifier": "[email protected]"
}
{- "available_options": [
- {
- "shopConfigurationId": "f1866880-9e0c-11eb-a4fd-0209510531db",
- "paymentMethods": [
- {
- "id": "9225337c-646f-11ef-a069-02a6417381c7",
- "type": "cash",
- "status": "active",
- "options": [
- {
- "id": "922fbaef-646f-11ef-a069-02a6417381c7",
- "name": "Paystack",
- "status": "active",
- "minAmount": 100,
- "maxAmount": null
}, - {
- "id": "922fb34f-646f-11ef-a069-02a6417381c7",
- "name": "PayPal",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}, - {
- "id": "922fb416-646f-11ef-a069-02a6417381c7",
- "name": "InterswitchRedirect",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}, - {
- "id": "922fb4ec-646f-11ef-a069-02a6417381c7",
- "name": "BankTransfer",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}, - {
- "id": "922fb5ae-646f-11ef-a069-02a6417381c7",
- "name": "MonnifyUSSD",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}
]
}, - {
- "id": "92253f8a-646f-11ef-a069-02a6417381c7",
- "type": "card",
- "status": "active",
- "options": [
- {
- "id": "922f9a82-646f-11ef-a069-02a6417381c7",
- "name": "Visa",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}, - {
- "id": "922f9e60-646f-11ef-a069-02a6417381c7",
- "name": "Mastercard",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}
]
}, - {
- "id": "92251654-646f-11ef-a069-02a6417381c7",
- "type": "bnpl",
- "status": "active",
- "options": [
- {
- "id": "922fba2e-646f-11ef-a069-02a6417381c7",
- "name": "EasyBuy",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}, - {
- "id": "922fb96d-646f-11ef-a069-02a6417381c7",
- "name": "CredPal",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}
]
}, - {
- "id": "92253c40-646f-11ef-a069-02a6417381c7",
- "type": "mobile_money",
- "status": "active",
- "options": [
- {
- "id": "922fbdf7-646f-11ef-a069-02a6417381c7",
- "name": "Opay",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}, - {
- "id": "922fbd32-646f-11ef-a069-02a6417381c7",
- "name": "Palmpay",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}
]
}, - {
- "id": "92253d08-646f-11ef-a069-02a6417381c7",
- "type": "mobile_payment_account",
- "status": "active",
- "options": [
- {
- "id": "922fb4ec-646f-11ef-a069-02a6417381c7",
- "name": "BankTransfer",
- "status": "active",
- "minAmount": 200,
- "maxAmount": 200
}, - {
- "id": "922fb5ae-646f-11ef-a069-02a6417381c7",
- "name": "MonnifyUSSD",
- "status": "active",
- "minAmount": 200,
- "maxAmount": 200
}
]
}
]
}, - {
- "shopConfigurationId": "f1867038-9e0c-11eb-a4fd-0209510531db",
- "paymentMethods": [
- {
- "id": "9225337c-646f-11ef-a069-02a6417381c7",
- "type": "cash",
- "status": "active",
- "options": [
- {
- "id": "922fbaef-646f-11ef-a069-02a6417381c7",
- "name": "Paystack",
- "status": "active",
- "minAmount": 100,
- "maxAmount": null
}, - {
- "id": "922fb34f-646f-11ef-a069-02a6417381c7",
- "name": "PayPal",
- "status": "active",
- "minAmount": null,
- "maxAmount": null
}
]
}
]
}
]
}
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.
shopConfigId required | string <uuid> Merchant shop configuration id provided by JumiaPay. |
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) |
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 120 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 |
Created
Bad Request: The request was unacceptable, due to missing required parameter
Unauthorized: Missing or invalid apiKey provided
The merchant does not have access to create new purchases.
The resource provided was not found
HTTP method not supported
The request was well-formed but was unable to be followed due to semantic errors
Something went wrong while communicating with JumiaPay
Sandbox URL
Production Url
{- "description": "JumiaPay order",
- "expirationTime": 30,
- "amount": {
- "value": 390,
- "currency": "NGN",
- "fee": 10
}, - "merchant": {
- "referenceId": "<YOUR_UNIQUE_MERCHANT_REFERENCE_ID>,",
- "token": "<YOUR_UNIQUE_MERCHANT_TOKEN>",
- "paymentOption": {
- "type": "d85cf934-13b3-47ee-92bb-1476388f4850",
- "option": "cc5cf934-13b3-47ee-92bb-1476388f4850"
}
}, - "consumer": {
- "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",
- "categoryCode": "Hotel"
}, - {
- "name": "Lagos Airport Hotel",
- "amount": "80",
- "quantity": "2",
- "currency": "NGN",
- "categoryCode": "Hotel"
}
], - "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}"
}
{- "purchaseId": "AAEAAADoKU7Uu5tJ9YDGV0bgjb4-siGzk4ackv3oao8qsZH3F1SidiKU",
- "status": "PENDING",
- "links": [
- {
- "method": "GET"
}
], - "jpay_trace_id": "42a20463bbec1f35e4c85139691bfc8f"
}
The Verify Status of Purchase request gives you visibility on the status changes of a purchase until its current status.
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) |
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". |
Success
Bad Request
Unauthorized: Missing Shop Config or API Key
Sandbox URL
Production Url
{- "shopConfig": "YOUR_SHOP_KEY",
- "transactionId": "AAEAAADpDFehqbrgASaL1jF9DYX6z4t9_bo3Sdb3adFUmCDS_Og3vBc4",
- "transactionType": "Purchase"
}
{- "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"
}
]
}
The Cancel Purchase request enables you to cancel a purchase when it is in one of the following status:
After a purchase is cancelled, the customer will be able to see it as 'Failed' on his JumiaPay account.
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) |
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. |
Success
Bad Request
Unauthorized: Missing Shop Config or API Key
Sandbox URL
Production Url
{- "shopConfig": "YOUR_SHOP_KEY",
- "purchaseId": "PURCHASE_ID"
}
{- "success": true,
- "type": "single",
- "payload": { }
}
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.
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) |
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:
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. |
Success
Bad Request
Unauthorized: Missing Shop Config or API Key
Sandbox URL
Production Url
{- "shopConfig": "YOUR_SHOP_KEY",
- "refundAmount": 5,
- "refundCurrency": "NGN",
- "description": "Refund for order #9182",
- "purchaseId": "AAEAAADpDFehqbrgASaL1jF9DYX6z4t9_bo3Sdb3adFUmCDS_Og3vBc4",
- "purchaseReferenceId": "",
- "referenceId": "YOUR_UNIQUE_REFUND_REFERENCE_ID"
}
{- "success": true,
- "type": "single",
- "payload": [ ]
}
This process allows you to create an agreement between a merchant's shop and a customer, which enables the merchant to debit the customer's JumiaPay account, or the underlying payment method, without customer interaction.
If the agreement is successfully created, you will receive an Agreement Callback with an Agreement Token, which can then be used in Create Purchase V2 with Agreement Token.
Do note that One Click and Recurring Payments may not be available for every merchant, and are subject to additional approval.
Obtain a redirect URL to initiate creation of an Agreement Token. Please redirect the customer to this URL, and If successful, the Agreement Token will be received via Agreement Callback.
In order to receive the callback, please add these query parameters to the URL provided in the respose when redirecting:
The Agreement Token is linked to a specific shopConfigId , and can not be used or shared with different shops, even at the same merchant.
shopConfigId required | string <uuid> Merchant shop configuration id provided by JumiaPay. |
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) |
Success
Bad Request: The request was unacceptable, due to missing required parameter
Unauthorized: Missing or invalid apiKey provided
The merchant does not have the feature enabled.
The resource provided was not found
HTTP method not supported
Something went wrong while communicating with the server
Sandbox URL
Production Url
curl -X GET \ 'https://api-staging-pay.jumia.com.ng/merchants/{shopConfigId}/recurring-types/one-touch' \ -H 'apikey: <YOUR_API_KEY>' \ -H 'Content-Type: application/json' \ -H 'cache-control: no-cache' \ }'
{- "links": [
- {
- "method": "GET"
}
]
}
This version of the Create Purchase V2 request allows you to process transactions through JumiaPay using an agreement token. 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.
shopConfigId required | string <uuid> Merchant shop configuration id provided by JumiaPay. |
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) |
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 120 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 |
agreement | object Agreement data information. |
Created
Bad Request: The request was unacceptable, due to missing required parameter
Unauthorized: Missing or invalid apiKey provided
The merchant does not have access to create new purchases.
The resource provided was not found
HTTP method not supported
The request was well-formed but was unable to be followed due to semantic errors
Something went wrong while communicating with JumiaPay
Sandbox URL
Production Url
{- "description": "JumiaPay order",
- "expirationTime": 30,
- "amount": {
- "value": 390,
- "currency": "NGN",
- "fee": 10
}, - "merchant": {
- "referenceId": "<YOUR_UNIQUE_MERCHANT_REFERENCE_ID>,",
- "token": "<YOUR_UNIQUE_MERCHANT_TOKEN>",
- "paymentOption": {
- "type": "d85cf934-13b3-47ee-92bb-1476388f4850",
- "option": "cc5cf934-13b3-47ee-92bb-1476388f4850"
}
}, - "consumer": {
- "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",
- "categoryCode": "hotel"
}, - {
- "name": "Lagos Airport Hotel",
- "amount": "80",
- "quantity": "2",
- "currency": "NGN",
- "categoryCode": "hotel"
}
], - "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}",
- "agreement": {
- "type": "installment",
- "token": "2eeebdd6-6bf1-42d2-900b-97fb22d9be47"
}
}
{- "purchaseId": "AAEAAADoKU7Uu5tJ9YDGV0bgjb4-siGzk4ackv3oao8qsZH3F1SidiKU",
- "status": "PENDING",
- "jpay_trace_id": "42a20463bbec1f35e4c85139691bfc8f"
}
A merchant must have the possibility to delete an agreement token from its user
shopConfigId required | string <uuid> Merchant shop configuration id provided by JumiaPay. |
agreementToken required | string <uuid> A unique value generated by you to identify a payment agreement with the payer to be deleted. |
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) |
No Content success status response code indicates that a request has succeeded, no action needs to be taken.
Unauthorized: Missing or invalid apiKey provided
The merchant does not have access to create new purchases.
Not found: The endpoint or page requested was not found
HTTP method not supported
The request was well-formed but was unable to be followed due to semantic errors
Something went wrong while communicating with JumiaPay
Sandbox URL
Production Url
curl -X DELETE 'https://api-staging-pay.jumia.com.ng/v2/merchants/{shopConfigId}/agreements/{agreementToken}' \ --header 'apiKey: <YOUR_API_KEY>' \ --header 'Content-Type: application/json'
{- "message": "No API key found in request"
}
Retrieve a list of one touch agreements and their data for a certain external request id at a specific shop. If a merchant does not receive a callback after creating an agreement, they can use this API to enquire about its details.
shopConfigId required | string <uuid> Merchant shop configuration id provided by JumiaPay. |
externalRequestId required | string <uuid> External identification provided by merchant to match the agreement token with a user. |
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) |
Success
Bad Request: The request was unacceptable, due to missing required parameter
Unauthorized: Missing or invalid apiKey provided
The merchant does not have the feature enabled.
The resource provided was not found
HTTP method not supported
Something went wrong while communicating with the server
Sandbox URL
Production Url
curl -X GET \ 'https://api-staging-pay.jumia.com.ng/v2/merchants/{shopConfigId}/agreements/one-touch?externalRequestId={externalRequestId}' \ -H 'apikey: <YOUR_API_KEY>' \ -H 'Content-Type: application/json' \ -H 'cache-control: no-cache'
[- {
- "status": "ACTIVE",
- "externalRequestId": "4a372e7d-25be-4e88-a77f-ce4be103282f",
- "agreementToken": "7d9dc209-576e-46e1-aca7-952eccc54cc6",
- "creationDateTime": "2018-04-04T09:59:48Z"
}, - {
- "status": "FAILED",
- "externalRequestId": "4a372e7d-25be-4e88-a77f-ce4be103282f",
- "agreementToken": "7d9dc209-576e-46e1-aca7-952eccc54cc6",
- "creationDateTime": "2018-04-04T09:59:48Z",
- "errorMessage": {
- "status": null,
- "details": {
- "value": {
- "error": "GENERAL_ERROR",
- "message": "The agreement has failed because this cards data was rejected by acquirer"
}
}, - "links": {
- "value": {
- "rel": "information_link",
- "method": "GET"
}
}, - "timestamp": "22-09-07 00:15:03.333 GMT",
- "internal_code": 10000,
- "jpay_trace_id": null
}
}
]
When a purchase transaction is created, JumiaPay will automatically notify you every time there's a change of its status. To do so, we'll send you a POST request to the purchaseCallbackUrl parameter provided by you on the Create Purchase request.
After receiving this request with success, we expect you to send JumiaPay a success message with status code 200. Otherwise, JumiaPay will keep sending the Callback to you up to 5 times until we get a successful response.
It's very important that you check the Callback request to confirm the transactions status before delivering value to the customer! Note that just because the customer reached your purchaseReturnUrl, it doesn't mean that the transaction is already successful. The transaction should only be considered successful when it reaches the status 'Completed' on JumiaPay side and never before.
Bellow, you'll find a brief explanation of the fields sent on the Callback request.
transactionEvents | Array of objects List of events for a specific transaction |
{- "transactionEvents": [
- {
- "id": "AAEAAAA6hpLxWNDtbGEu9SKCl8ivNNHs3luQrpBi17C8jkcRtsWf3I5t",
- "creationDateTime": "2018-04-04T09:59:48Z",
- "transactionType": "Purchase",
- "newStatus": "Created",
- "oldStatus": null,
- "transactionId": "AAEAAADoKU7Q321mnk6XFV_4zvOamJidaWFOstEyMDX-YSMJBwgC0cTW",
- "merchantReferenceId": "1522835946",
- "shopConfigurationId": "AAEAAADoKU7YItWSEhYpJRb0fV842USafymz4Vs2onKOPsMPlnU9LFrt",
- "paymentInstrumentType": "CreditCard",
- "paymentInstrumentShareableId": "46ffde60-c637-49db-9f63-a05a8f4cb3e8",
- "paymentMethod": "Mastercard",
- "paymentOption": null
}, - {
- "id": "AAEAAAA6hpLxWNDtbGEu9SKCl8ivNNHs3luQrpBi17C8HGcRtsWf3I5t",
- "creationDateTime": "2018-04-04T09:59:48Z",
- "transactionType": "Purchase",
- "newStatus": "Confirmed",
- "oldStatus": "Created",
- "transactionId": "AAEAAADoKU7Q321mnk6XFV_4zvOamJidaWFOstEyMDX-YSMJBwgC0cTW",
- "merchantReferenceId": "1522835946",
- "shopConfigurationId": "AAEAAADoKU7YItWSEhYpJRb0fV842USafymz4Vs2onKOPsMPlnU9LFrt",
- "paymentInstrumentType": "CreditCard",
- "paymentInstrumentShareableId": "46ffde60-c637-49db-9f63-a05a8f4cb3e8",
- "paymentMethod": "Mastercard",
- "paymentOption": {
- "type": "d85cf934-13b3-47ee-92bb-1476388f4850",
- "option": "d85cf934-13b3-47ee-92bb-1476388f4851"
}
}, - {
- "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",
- "paymentInstrumentShareableId": "46ffde60-c637-49db-9f63-a05a8f4cb3e8",
- "paymentMethod": "Mastercard",
- "paymentOption": {
- "type": "d85cf934-13b3-47ee-92bb-1476388f4850",
- "option": "d85cf934-13b3-47ee-92bb-1476388f4851"
}
}, - {
- "id": "AAEAAAA6hpLxABo_oVfSAqSGXK8LgOjG_5sfMlTCjjQGpkdMz3zTqdsk",
- "creationDateTime": "2018-04-04T09:59:48Z",
- "transactionType": "Purchase",
- "newStatus": "Completed",
- "oldStatus": "Committed",
- "transactionId": "AAEAAADoKU7Q321mnk6XFV_4zvOamJidaWFOstEyMDX-YSMJBwgC0cTW",
- "merchantReferenceId": "1522835946",
- "shopConfigurationId": "AAEAAADoKU7YItWSEhYpJRb0fV842USafymz4Vs2onKOPsMPlnU9LFrt",
- "paymentInstrumentType": "CreditCard",
- "paymentInstrumentShareableId": "46ffde60-c637-49db-9f63-a05a8f4cb3e8",
- "paymentMethod": "Mastercard",
- "paymentOption": {
- "type": "d85cf934-13b3-47ee-92bb-1476388f4850",
- "option": "d85cf934-13b3-47ee-92bb-1476388f4851"
}
}
]
}
When the user finish the process of creating a new agreement, JumiaPay will automatically notify the merchant. To do so, JumiaPay will send HTTP POST request to the callback URL parameter provided by the merchant on the redirect page, where the merchant will send the user to JumiaPay.
If for some reason the callback did not reached your system, JumiaPay will cancel the agreement's creation. The user will be able to try to create another agreement.
Bellow, you'll find a brief explanation of the fields sent on the Callback request if the Agreement creation succeded.
agreementToken | string <UUID> A unique value generated by you to identify a payment agreement with the payer. You also need to submit it on subsequent merchant-initiated transactions to link payments in a series. This is required to comply with card scheme mandates where the Agreement ID acts as an identifier to link the preceding cardholder-initiated transaction to the subsequent merchant-initiated payments. |
externalRequestId | string External identification provided by merchant to match the agreement token with a user |
status | string Value: "ACTIVE" Agreement details
|
{- "agreementToken": "b69ac853-0170-4399-bdda-b3d4834e6b22",
- "externalRequestId": "externalRequestId",
- "status": "ACTIVE"
}
Bellow, you'll find a brief explanation of the fields sent on the Callback request if the Agreement is Expired.
agreementToken | string <UUID> A unique value generated by you to identify a payment agreement with the payer. You also need to submit it on subsequent merchant-initiated transactions to link payments in a series. This is required to comply with card scheme mandates where the Agreement ID acts as an identifier to link the preceding cardholder-initiated transaction to the subsequent merchant-initiated payments. |
externalRequestId | string External identification provided by merchant to match the agreement token with a user |
status | string Value: "EXPIRED" Agreement details
|
{- "agreementToken": "b69ac853-0170-4399-bdda-b3d4834e6b22",
- "externalRequestId": "externalRequestId",
- "status": "EXPIRED"
}
Bellow, you'll find a brief explanation of the fields sent on the Callback request if the Agreement creation failed.
externalRequestId | string External identification provided by merchant to match the agreement token with a user |
error | object Error details |
{- "externalRequestId": "externalRequestId",
- "error": {
- "internal_code": "200401",
- "details": [
- {
- "error": "The Operation is not being processed due to semantic errors.",
- "message": "JumiaPay is unable to process the request. Please contact JumiaPay support for more information giving the jpay_trace_id and the internal_code from the response.\n"
}
], - "links": [
- {
- "rel": "information_link",
- "method": "GET"
}
], - "jpay_trace_id": "418d6cea-24e1-11eb-adc1-0242ac120002",
- "timestamp": "2020-11-11T14:14:45.624+0000"
}
}
JumiaPay error codes
Error Code | Description |
---|---|
10000 | General Error in case of unexpected error in JumiaPay |
20110 | Invalid fields provided to the JumiaPay |
20231 | Recurring payments feature is disabled |
20232 | Merchant does not have access to the feature |
20235 | Unknown merchant |
20271 | HTTP method is not supported to the resource |
20240 | Agreement token does not have access to the feature |
20257 | Agreement token cannot be deleted |
20282 | Duplicated merchant refrence identification |
20284 | Agreement token is not active |
20285 | Agreement token provided does not match with recurring type |
This operation has been deprecated and replaced by Create Purchase V2. It is being preserved to ensure backwards compatibility, but you are strongly encouraged to update to our latest APIs. You may find the original documentation below for your reference.
The Create Purchase request allows you to process transactions through JumiaPay.
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) |
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. |
priceAmount required | string Price amount of the purchase. This amount will be transferred to your business shop wallet. The priceAmount 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 |
priceCurrency required | string Enum: "NGN" "EGP" "KES" "GHS" "MAD" "XOF" "TND" "UGX" Price currency corresponds to official ISO 4217 currency codes:
|
merchantReferenceId required | string <= 255 characters Merchant’s unique reference id generated by you for the purchase. This is an alphanumeric field with a maximum length of 255 characters. |
purchaseReturnUrl required | string <url> Return url to the business website once the transaction is created on JumiaPay. This url must be provided by you. |
purchaseCallbackUrl required | string <url> Purchase callback url to which JumiaPay will send the purchases’ status update. This url must be provided by you. You may find an example of the request body that JumiaPay will send to you upon callback here. |
consumerData required | object Customer's data necessary to create a purchase. |
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. |
description | string Brief description of the purchase. This description is for internal use only, it will not be visible to the customer. |
shippingAddress | object Shipping data to which the products will be delivered. |
billingAddress | object Billing data information. |
Success
Bad Request
Unauthorized: Missing Shop Config or API Key
Sandbox URL
Production Url
{- "shopConfig": "YOUR_SHOP_KEY",
- "priceAmount": "390",
- "priceCurrency": "NGN",
- "merchantReferenceId": "<YOUR_UNIQUE_MERCHANT_REFERENCE_ID>",
- "consumerData": {
- "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": {
- "basketItems": [
- {
- "name": "Lagos Airport Hotel",
- "amount": "230",
- "quantity": "1",
- "currency": "NGN"
}, - {
- "name": "Lagos Airport Hotel",
- "amount": "80",
- "quantity": "2",
- "currency": "NGN"
}
], - "currency": "NGN",
- "shipping": "0"
}, - "description": "Hotel booking",
- "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"
}
}
{- "success": true,
- "type": "single",
- "payload": {
- "purchaseId": "AAEAAADoKU7Uu5tJ9YDGV0bgjb4-siGzk4ackv3oao8qsZH3F1SidiKU",
}
}