logo
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:

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.ci/b2ccredits/api/v1/single-credits/{creditWalletAccountId}

Production Url

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "Credit 123",
  • "description": "Example description",
  • "amount": "10",
  • "currency": "NGN",
  • "customer_email": "[email protected]",
  • "expiration_date": "2021-03-27T23:59:59Z",
  • "callback_url": "https://example.com/callback",
  • "partner_credit_id": "HCgfE"
}

Response samples

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": "[email protected]",
  • "status":
    {
    • "id": "processing_delivery",
    • "label": "Processing Delivery"
    },
  • "in_approval": false,
  • "expiration_date": null,
  • "callback_url": "https://example.com/callback",
  • "created":
    {},
  • "updated":
    {},
  • "submitted":
    {},
  • "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.ci/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/{singleCreditUuid}

Production Url

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

Response samples

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": "[email protected]",
  • "status":
    {
    • "id": "processing_delivery",
    • "label": "Processing Delivery"
    },
  • "in_approval": false,
  • "expiration_date": null,
  • "callback_url": "https://example.com/callback",
  • "created":
    {},
  • "updated":
    {},
  • "submitted":
    {},
  • "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.ci/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/partner-id/{partnerCreditId}

Production Url

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

Response samples

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": "[email protected]",
  • "status":
    {
    • "id": "processing_delivery",
    • "label": "Processing Delivery"
    },
  • "in_approval": false,
  • "expiration_date": null,
  • "callback_url": "https://example.com/callback",
  • "created":
    {},
  • "updated":
    {},
  • "submitted":
    {},
  • "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.ci/b2ccredits/api/v1/single-credits/{creditWalletAccountId}/{singleCreditUuid}/cancel

Production Url

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

Response samples

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": "[email protected]",
  • "status":
    {
    • "id": "processing_cancellation",
    • "label": "Processing Cancellation"
    },
  • "in_approval": false,
  • "expiration_date": null,
  • "callback_url": null,
  • "created":
    {},
  • "updated":
    {},
  • "submitted":
    {},
  • "approved": null,
  • "declined": null,
  • "cancelled":
    {}
}

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": "[email protected]",
    • "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": "[email protected]",
    • "status":
      {
      • "id": "delivered",
      • "label": "Delivered"
      },
    • "expiration_date": null,
    • "error_message": null
    }
}