credits-api-doc-pay.jumia.co.ke Open in urlscan Pro
2606:4700::6812:712b Public Scan

Back to summary
URL:
https://credits-api-doc-pay.jumia.co.ke/
Submission: On November 30 via api (November 30th 2024, 9:39:26 am UTC) from US — Scanned from DE
Form analysis
0 forms found in the DOM

Text Content

 * Authentication
 * Credit account
 * API Endpoints
 * API Endpoints
   * Single credits
     * postCreate a single credit
     * getGet a single credit
     * getGet a single credit using partner id
     * postCancel a single credit
 * Callback
   * Callback

Documentation Powered by ReDoc





JUMIAPAY CREDITS API (V1)



Welcome to JumiaPay Credits API Documentation!


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.


BUSINESS ACCOUNT ID

The authentication is connected with one or multiple business accounts.

You need to identify the business account in all requests by sending it in the
X-Business-Area header. This information is available on the profile page of
your business areas. Requests without this information will fail authentication
and return status code 401 Unauthorized.


CREDIT ACCOUNT

The source of the funds to give credits is a "Credit" account. They are
configured and provided by us. All requests need this information as part of the
URL.


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/b2ccredits
 * Production Url: https://api-pay.jumia.co.ke/b2ccredits


SINGLE CREDITS

The single credits feature allows businesses to give credits to specific users.
This feature is available in the business area web and API interfaces.


CREATE A SINGLE CREDIT

This request allows creating a new single credit.

This request will return success when is valid, the credit creation will be
processed in the background. Checking if the Credit account has enough balance
is only done when disbursing the credit to the customer; a lack of balance means
the credits will fail.

When creating a single credit in the business area web interface there is an
approval step. Single credits created using the API are automatically approved.

PATH PARAMETERS

creditWalletAccountId
required
string

Identifier of the Credit account

HEADER PARAMETERS

apikey
required
string

Fill in with the API key shared by our team

X-Business-Area
required
string
Example: 01234567-abcd-0000-1111-abc123456789

Identifier of the business account

REQUEST BODY SCHEMA: APPLICATION/JSON



name
required
string <= 50 characters

Name of the single credit. It's a "human" identifier of the credit that can be
visible to the customer.

Example: Campaign voucher

description
required
string <= 255 characters

Description of the credit. Not visible to the customer

Example: Credit for customer due to refund issue.

amount
required
string

Amount of the credit to create, in the country currency.

The amount must follow the maximum decimal places allowed for the currency. A
decimal point must be used to separate the integer part from the fractional part
of the number.

Example: 100.99

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

Price currency corresponds to official ISO 4217 currency codes:

 * Nigeria: NGN, 2 decimal places
 * Egypt: EGP, 2 decimal places
 * Ghana: GHS, 2 decimal places
 * Kenya: KES, 2 decimal places
 * Morocco: MAD, 2 decimal places
 * Ivory Coast: XOF, no decimal places
 * Tunisia: TND, 2 decimal places
 * Uganda: UGX, no decimal places
 * Algeria: DZD, 2 decimal places

customer_email
required
string <email>

Customer email to give the credit.

expiration_date
string <datetime> yyyy-MM-ddTHH:mm:ssZ

Optional expiration date of the credit. Must be sent in UTC and be in the
future.

If sent, after this time the customer will no longer be able to use the credit
and the unused amount is returned back to the source Credit account.

Example: 2021-03-27T23:59:59Z

callback_url
string <url>

Optional URL used to send callbacks with notifications. If sent must use HTTPS
protocol.

Callbacks support query parameters and will be sent using POST.

partner_credit_id
string

Optional identification generated by partner. If sent must be unique for the
Credit account.


RESPONSES

201

Success

400

Bad Request

401

Missing or invalid credentials

500

Generic error

post/api/v1/single-credits/{creditWalletAccountId}

Sandbox URL

https://api-sandbox-pay.jumia.co.ke/b2ccredits/api/v1/single-credits/{creditWalletAccountId}

Production Url

https://api-pay.jumia.co.ke/b2ccredits/api/v1/single-credits/{creditWalletAccountId}


REQUEST SAMPLES

 * Payload

Content type
application/json
Copy
Expand all Collapse all

{
 * "name": "Credit 123",
 * "description": "Example description",
 * "amount": "10",
 * "currency": "NGN",
 * "customer_email": "test@example.com",
 * "expiration_date": "2021-03-27T23:59:59Z",
 * "callback_url": "https://example.com/callback",
 * "partner_credit_id": "HCgfE"

}


RESPONSE SAMPLES

 * 201
 * 400
 * 401
 * 500

Content type
application/json
Copy
Expand all Collapse all

{
 * "uuid": "f74f6658-0168-447e-8b15-b468ec792278",
 * "partner_credit_id": "HCgfE",
 * "name": "Credit 123",
 * "description": "Example description",
 * "source_wallet_account_id":
   "AAE2wHesP7tcrYrrLccZss_XJq8FEucQsj-k_I4o2PDvwR7X2",
 * "amount":
   
   {
    * "value": 10,
    * "currency": "NGN",
    * "symbol": "NGN",
    * "formatted_value": "NGN 10"
   
   },
 * "usage":
   
   {
    * "value": 0,
    * "currency": "NGN",
    * "symbol": "NGN",
    * "formatted_value": "NGN 0"
   
   },
 * "customer_email": "test@example.com",
 * "status":
   
   {
    * "id": "processing_delivery",
    * "label": "Processing Delivery"
   
   },
 * "in_approval": false,
 * "expiration_date": null,
 * "callback_url": "https://example.com/callback",
 * "created":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "updated":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "submitted":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "approved": null,
 * "declined": null,
 * "cancelled": null

}





GET A SINGLE CREDIT

This request returns the details of the single credit identified using it's
internal identifier.

PATH PARAMETERS

creditWalletAccountId
required
string

Identifier of the Credit account

singleCreditUuid
required
string

Identifier of the single credit

HEADER PARAMETERS

apikey
required
string

Fill in with the API key shared by our team

X-Business-Area
required
string
Example: 01234567-abcd-0000-1111-abc123456789

Identifier of the business account


RESPONSES

200

Success

401

Missing or invalid credentials

404

Single credit not found

500

Generic error

get/api/v1/single-credits/{creditWalletAccountId}/{singleCreditUuid}

Sandbox URL

https://api-sandbox-pay.jumia.co.ke/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/{singleCreditUuid}

Production Url

https://api-pay.jumia.co.ke/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/{singleCreditUuid}


RESPONSE SAMPLES

 * 200
 * 401
 * 500

Content type
application/json
Example
Processing delivery

Copy
Expand all Collapse all

{
 * "uuid": "f74f6658-0168-447e-8b15-b468ec792278",
 * "partner_credit_id": "HCgfE",
 * "name": "Credit 123",
 * "description": "Example description",
 * "source_wallet_account_id":
   "AAE2wHesP7tcrYrrLccZss_XJq8FEucQsj-k_I4o2PDvwR7X2",
 * "amount":
   
   {
    * "value": 10,
    * "currency": "NGN",
    * "symbol": "NGN",
    * "formatted_value": "NGN 10"
   
   },
 * "usage":
   
   {
    * "value": 0,
    * "currency": "NGN",
    * "symbol": "NGN",
    * "formatted_value": "NGN 0"
   
   },
 * "customer_email": "test@example.com",
 * "status":
   
   {
    * "id": "processing_delivery",
    * "label": "Processing Delivery"
   
   },
 * "in_approval": false,
 * "expiration_date": null,
 * "callback_url": "https://example.com/callback",
 * "created":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "updated":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "submitted":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "approved": null,
 * "declined": null,
 * "cancelled": null

}




GET A SINGLE CREDIT USING PARTNER ID

This request returns the details of the single credit identified by the partner
credit id.

PATH PARAMETERS

creditWalletAccountId
required
string

Identifier of the Credit account

partnerCreditId
required
string

Identifier of the single credit generated by partner

HEADER PARAMETERS

apikey
required
string

Fill in with the API key shared by our team

X-Business-Area
required
string
Example: 01234567-abcd-0000-1111-abc123456789

Identifier of the business account


RESPONSES

200

Success

401

Missing or invalid credentials

404

Single credit not found

500

Generic error

get/api/v1/single-credits/{creditWalletAccountId}/partner-id/{partnerCreditId}

Sandbox URL

https://api-sandbox-pay.jumia.co.ke/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/partner-id/{partnerCreditId}

Production Url

https://api-pay.jumia.co.ke/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/partner-id/{partnerCreditId}


RESPONSE SAMPLES

 * 200
 * 401
 * 500

Content type
application/json
Example
Processing delivery

Copy
Expand all Collapse all

{
 * "uuid": "f74f6658-0168-447e-8b15-b468ec792278",
 * "partner_credit_id": "HCgfE",
 * "name": "Credit 123",
 * "description": "Example description",
 * "source_wallet_account_id":
   "AAE2wHesP7tcrYrrLccZss_XJq8FEucQsj-k_I4o2PDvwR7X2",
 * "amount":
   
   {
    * "value": 10,
    * "currency": "NGN",
    * "symbol": "NGN",
    * "formatted_value": "NGN 10"
   
   },
 * "usage":
   
   {
    * "value": 0,
    * "currency": "NGN",
    * "symbol": "NGN",
    * "formatted_value": "NGN 0"
   
   },
 * "customer_email": "test@example.com",
 * "status":
   
   {
    * "id": "processing_delivery",
    * "label": "Processing Delivery"
   
   },
 * "in_approval": false,
 * "expiration_date": null,
 * "callback_url": "https://example.com/callback",
 * "created":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "updated":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "submitted":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "approved": null,
 * "declined": null,
 * "cancelled": null

}




CANCEL A SINGLE CREDIT

This request allows cancelling a single credit. A single credit can only be
cancelled when its status is delivered. Cancelling a credit means the non-spent
funds will return to the origin Credit account.

This request will return success when is valid, the credit cancellation will be
processed in the background.

PATH PARAMETERS

creditWalletAccountId
required
string

Identifier of the Credit account

singleCreditUuid
required
string

Identifier of the single credit

HEADER PARAMETERS

apikey
required
string

Fill in with the API key shared by our team

X-Business-Area
required
string
Example: 01234567-abcd-0000-1111-abc123456789

Identifier of the business account


RESPONSES

200

Success

400

Bad Request

401

Missing or invalid credentials

404

Single credit not found

500

Generic error

post/api/v1/single-credits/{creditWalletAccountId}/{singleCreditUuid}/cancel

Sandbox URL

https://api-sandbox-pay.jumia.co.ke/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/{singleCreditUuid}/cancel

Production Url

https://api-pay.jumia.co.ke/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/{singleCreditUuid}/cancel


RESPONSE SAMPLES

 * 200
 * 400
 * 401
 * 500

Content type
application/json
Copy
Expand all Collapse all

{
 * "uuid": "f74f6658-0168-447e-8b15-b468ec792278",
 * "partner_credit_id": "HCgfE",
 * "name": "Credit 123",
 * "description": "Example description",
 * "source_wallet_account_id":
   "AAE2wHesP7tcrYrrLccZss_XJq8FEucQsj-k_I4o2PDvwR7X2",
 * "amount":
   
   {
    * "value": 10,
    * "currency": "NGN",
    * "symbol": "NGN",
    * "formatted_value": "NGN 10"
   
   },
 * "usage":
   
   {
    * "value": 0,
    * "currency": "NGN",
    * "symbol": "NGN",
    * "formatted_value": "NGN 0"
   
   },
 * "customer_email": "test@example.com",
 * "status":
   
   {
    * "id": "processing_cancellation",
    * "label": "Processing Cancellation"
   
   },
 * "in_approval": false,
 * "expiration_date": null,
 * "callback_url": null,
 * "created":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "updated":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "submitted":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:23:56Z"
   
   },
 * "approved": null,
 * "declined": null,
 * "cancelled":
   
   {
    * "user": "api-ba_id@email.com",
    * "datetime": "2021-04-16T10:25:16Z"
   
   }

}





CALLBACK

We can send callback notifications on some events if a callback URL was
provided.

The callback URL must return HTTP 2xx to be considered success. If other code is
returned, ot there is some error calling it, we will retry up to 5 times.

CREDIT_STATUS_CHANGE

This notification will be sent when the credit changes status to one of the
following:

 * delivered
 * failed
 * cancelled
 * expired
 * cancellation_failed*
 * expiration_failed*

*Note: Is possible that the credit changes from an error state to it's
corresponding success state (for example from cancellation_failed to cancelled).

Bellow, you'll find a brief explanation of the fields sent on the Callback
request.

type
string

Notification type, in this case CREDIT_STATUS_CHANGE.

datetime
string <datetime> yyyy-MM-ddTHH:mm:ssZ

Original time of the callback

old_status
string Nullable

Old credit status

new_status
string Nullable

New credit status

credit
object

A simplified version of the single credit

Copy
Expand all Collapse all

{
 * "type": "CREDIT_STATUS_CHANGE",
 * "datetime": "2021-05-13T08:21:59.265720Z",
 * "old_status": "processing_delivery",
 * "new_status": "delivered",
 * "status": null,
 * "credit":
   
   {
    * "uuid": "f74f6658-0168-447e-8b15-b468ec792278",
    * "partner_credit_id": "HCgfE",
    * "name": "Credit 123",
    * "description": "Example description",
    * "source_wallet_account_id":
      "AAE2wHesP7tcrYrrLccZss_XJq8FEucQsj-k_I4o2PDvwR7X2",
    * "amount":
      
      {
       * "value": 10,
       * "currency": "NGN",
       * "symbol": "NGN",
       * "formatted_value": "NGN 10"
      
      },
    * "usage":
      
      {
       * "value": 5,
       * "currency": "NGN",
       * "symbol": "NGN",
       * "formatted_value": "NGN 5"
      
      },
    * "old_usage": null,
    * "new_usage": null,
    * "customer_email": "test@example.com",
    * "status":
      
      {
       * "id": "delivered",
       * "label": "Delivered"
      
      },
    * "expiration_date": null,
    * "error_message": null
   
   }

}

CREDIT_USAGE_UPDATE

This notification will be sent when the usage of the credit is updated, with the
information about the old and new usage values of the credits.

Bellow, you'll find a brief explanation of the fields sent on the Callback
request.

type
string

Notification type, in this case CREDIT_USAGE_UPDATE

datetime
string <datetime> yyyy-MM-ddTHH:mm:ssZ

Original time of the callback

status
string

Current credit status

credit
object

A simplified version the single credit

Copy
Expand all Collapse all

{
 * "type": "CREDIT_USAGE_UPDATE",
 * "datetime": "2021-05-13T08:21:59.265720Z",
 * "status": "delivered",
 * "old_status": null,
 * "new_status": null,
 * "credit":
   
   {
    * "uuid": "f74f6658-0168-447e-8b15-b468ec792278",
    * "partner_credit_id": "HCgfE",
    * "name": "Credit 123",
    * "description": "Example description",
    * "source_wallet_account_id":
      "AAE2wHesP7tcrYrrLccZss_XJq8FEucQsj-k_I4o2PDvwR7X2",
    * "amount":
      
      {
       * "value": 10,
       * "currency": "NGN",
       * "symbol": "NGN"
      
      },
    * "formatted_value": "NGN 10",
    * "usage": null,
    * "old_usage":
      
      {
       * "value": 10,
       * "currency": "NGN",
       * "symbol": "NGN",
       * "formatted_value": "NGN 0"
      
      },
    * "new_usage":
      
      {
       * "value": 0,
       * "currency": "NGN",
       * "symbol": "NGN",
       * "formatted_value": "NGN 0"
      
      },
    * "customer_email": "test@example.com",
    * "status":
      
      {
       * "id": "delivered",
       * "label": "Delivered"
      
      },
    * "expiration_date": null,
    * "error_message": null
   
   }

}
credits-api-doc-pay.jumia.co.ke Open in urlscan Pro 2606:4700::6812:712b Public Scan

Form analysis 0 forms found in the DOM

Text Content

credits-api-doc-pay.jumia.co.ke Open in urlscan Pro
2606:4700::6812:712b Public Scan

Form analysis
0 forms found in the DOM
