NAV Navbar
curl

API Version

This is the documentation for Relworx payments API version 2. API version 2 is currently the default api version.

Introduction

Welcome to Relworx Payments API. This API enables you to integrate online payments into your internet business. Our developer friendly API gives you access to mobile money in Uganda on MTN / Airtel networks and Kenya Safaricom MPESA, where you can request or send payments to valid mobile money subscribers.

Getting Started

Please follow the steps below to setup your account with Relworx and start receiving or sending payments;

  1. Sign Up. A confirmation email will be sent to your email address for email verification. Simply click on confirmation link sent in email to complete sign up.

  2. Login to your dashboard where you can perform several actions to manage your account. Here you can create business accounts, manage your API keys.

  3. Create a business account. You can create a business account for your business, organization, branch or any entity on whose behalf you wish to start receiving or sending payments.

  4. Generate your API Key. API keys are used to authenticate your API requests. Generate your API key and store it safely.

API Endpoint

Relworx Payments API can be reached at the following endpoint;

Error Handling

Relworx API uses HTTP status codes to indicate success or failure of a request. Below is a summary of the HTTP status codes you should expect to handle.

Common Error Codes

Code Meaning
200 OK - Request was successful
400 Bad Request - Malformed request or missing required parameters
401 Unauthorized - Missing token, expired token
403 Forbidden - You are trying to access a resource for which you don't have proper access rights.
404 Not Found - You are trying to access a resource that does not exist
422 Unprocessable Entity - You provided all the required parameters but they are not proper for the request
500 Internal Server Error - We had a glitch in our servers. Retry the request in a little while or contact support
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Authentication

Relworx API uses token authentication. To make an authenticated request to your API, you need to pass your generated API key via the request header. Generate your API Key

Mobile Money

Request Payment

This api endpoint requests for a payment from a mobile money subscriber.

HTTP Request

Sample payment request

Make sure to replace <--Your API Key--> with your generated API Key.


curl "https://payments.relworx.com/api/mobile-money/request-payment" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.relworx.v2" \
  -H "Authorization: Bearer <--Your API Key-->" \
  -d '{
        "account_no": "RELJH012BV45P",
        "reference": "52750b30ffbc7de3b36",
        "msisdn": "+256701345672",
        "currency": "UGX",
        "amount": 500.00,
        "description": "Payment Request."
    }'

Sample response.

  {
    "success": true,
    "message": "Request payment in progress.",
    "internal_reference": "d3ae5e14f05fcc58427331d38cb11d42"
  }

Arguments

Parameter Type Required Description
account_no string Required Business account number. This is generated for you when you create a business account.
reference string Required A unique generated string to identify your request. A minimum of 8 and maximum of 36 characters is allowed.
msisdn string Required Mobile money subscribers phone number from which to deduct payment. Should be internationally formatted. for-example +256701345678
currency string Required 3 letter ISO currency code for example UGX. No currency conversion is done, so the currency must be valid for the given phone number (msisdn). Currently we support UGX and KES.
amount decimal Required Amount to be deducted from mobile money subscriber’s account.
description string Optional A description for the request.

Send Payment

This api endpoint sends payment to a mobile money subscriber.

HTTP Request

Sample send payment request

Make sure to replace <--Your API Key--> with your generated API Key.


curl "https://payments.relworx.com/api/mobile-money/send-payment" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.relworx.v2" \
  -H "Authorization: Bearer <--Your API Key-->" \
  -d '{
        "account_no": "RELJH012BV45P",
        "reference": "52750b30ffbc7de3b36",
        "msisdn": "+256701345672",
        "currency": "UGX",
        "amount": 500.00,
        "description": "Send Payment to John Doe."
    }'

Sample response.

{
    "success": true,
    "message": "Send payment in progress.",
    "internal_reference": "d3ae5e14f05fcc58427331d38cb11d42"
}

Arguments

Parameter Type Required Description
account_no string Required Business account number. This is generated for you when you create a business account.
reference string Required A unique generated string to identify your request. A minimum of 8 and maximum of 36 characters is allowed.
msisdn string Required The recipient’s mobile money account number to which the money will be sent. Should be internationally formatted for-example +256701345672.
currency string Required 3 letter ISO currency code for example UGX. No currency conversion is done, so the currency must be valid for the given phone number (msisdn). Currently we support UGX and KES.
amount decimal Required Amount to be sent to recipient’s mobile money account.
description string Optional A description for the request.

Validate Mobile Number

This api endpoint validates a mobile money subscriber’s phone number.

HTTP Request

Sample validate mobile number request.

Make sure to replace <--Your API Key--> with your obtained api key.

 curl "https://payments.relworx.com/api/mobile-money/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.relworx.v2" \
  -H "Authorization: Bearer <--Your API Key-->" \
  -d '{
        "msisdn": "+256703560861"
    }'

Arguments

Parameter Type Required Description
msisdn string Required Mobile money subscriber’s phone number. Should be internationally formatted for-example +256701345674. Only Airtel Uganda phone numbers are supported for validation at the moment.

HTTP Response

Sample response:

{
    "success": true,
    "message": "Msisdn +256701345674 successfully validated.",
    "customer_name": "CUSTOMER NAME"
}

Arguments

Parameter Type Description
customer_name string Shows registered customer name for specified msisdn.

Check Wallet Balance

This endpoint checks balance on a mobile money wallet.

HTTP Request

Sample check wallet balance request.

Make sure to replace <--Your API Key--> with your obtained api key.

   curl -i -H "Accept: application/vnd.relworx.v2" -H "Content-Type: application/json" -H "Authorization: Bearer <--Your API Key-->" https://payments.relworx.com/api/mobile-money/check-wallet-balance\?account_no\=RELB0C798FGHVCS\&currency\=UGX

Arguments

Parameter Type Required Description
account_no string Yes Business account number. This is generated for you when you create a business account.
currency string Yes 3 letter ISO currency code for example UGX.

HTTP Response

Sample response:

{
    "success": true,
    "balance": 0.0,
}

Arguments

Parameter Type Description
balance string Balance on mobile money wallet.

Visa / Mastercard

Request Payment Session

This endpoint requests a payment session for VISA/Mastercard.

Sample request to get a payment session

curl "https://payments.relworx.com/api/visa/request-session" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.relworx.v2" \
  -H "Authorization: Bearer <--Your API Key-->" \
  -d '{
        "account_no": "RELJH012BV45P",
        "reference": "52750b30ffbc7de3b36",
        "currency": "UGX",
        "amount": 10000.00,
        "description": "Payment Request.",
    }'

Sample response. Load returned payment_url to access visa payment form.

{
    "success": true,
    "message": "Visa/Mastercard payment url generated successfully.",
    "payment_url": "https://payments.relworx.com/merchant-payment/1573621698448/visa-mastercard"
}

HTTP Request

Arguments

Parameter Type Required Description
account_no string Yes Business account number. This is generated for you when you create a business account.
reference string Yes A unique generated string to identify your request. A minimum of 8 and maximum of 36 characters is allowed.
currency string Yes 3 letter ISO currency code for example UGX. No currency conversion is done. Currently we support UGX and USD.
amount decimal Yes Amount to be deducted from Visa/Mastercard card holder.
description string No A description for the request.

Auto Return

The Auto Return feature for Visa/Mastercard redirects the buyer back to your website after payment has completed, failed or due to an error. Here's how to enable Auto Return:

  1. Login to your dashboard and click on accounts.
  2. Click on view button for the business account you use for visa/mastercard payments.
  3. You can view your current Auto Return configuration under settings. Click on edit business account button to change settings.

When you enable Auto Return and configure URL's for Auto Return, the target page must meet the following requirements.

Generate verification signature to verify Auto Return:

/**
 * @param string $webhook_key the webhooks authentication key
 * @param string $url the webhook url
 * @param string $timestamp the signature timestamp
 * @param array $params the requests POST parameters
 */

// This data is posted to your configured auto-return
// URL plus a relworx_signature value you can compare with to verify request

//Only include these from received POST data.
$params = array(
  "status" => "success",
  "customer_reference" => "shdfjsue789sh8jshuehu",
  "internal_reference" => "jshfufehkshffkseuhfskahakhuefak",
);

function generateSignature($webhook_key, $timestamp, $url, $params) {
    $signed_data = $url;
    $signed_data .= $timestamp;
    ksort($params);
    foreach ($params as $key => $value) {
        $signed_data .= strval($key);
        $signed_data .= strval($value);
    }

    return hash_hmac('sha256', $signed_data, $webhook_key, false);
}

Products

Available Products

This API endpoint provides a list of products available for purchase.

HTTP Request

Sample request to get list of available products.

Make sure to replace <--Your API Key--> with your generated API Key.

   curl -i -H "Accept: application/vnd.relworx.v2" -H "Content-Type: application/json" -H "Authorization: Bearer <--Your API Key-->" https://payments.relworx.com/api/products

Sample response.

{
    "success": true,
    "products": [
        {
            "name": "Africell Uganda Airtime",
            "code": "AFRICELL_UG_AIRTIME",
            "category": "AIRTIME",
            "has_price_list": false,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "Airtel Uganda Airtime",
            "code": "AIRTEL_UG_AIRTIME",
            "category": "AIRTIME",
            "has_price_list": false,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "MTN Uganda Airtime",
            "code": "MTN_UG_AIRTIME",
            "category": "AIRTIME",
            "has_price_list": false,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "Uganda Telecom Airtime",
            "code": "UTL_AIRTIME",
            "category": "AIRTIME",
            "has_price_list": false,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "Africell Uganda Internet",
            "code": "AFRICELL_UG_INTERNET",
            "category": "INTERNET",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "MTN Uganda Internet",
            "code": "MTN_UG_INTERNET",
            "category": "INTERNET",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "Smile Uganda Internet",
            "code": "SMILE_UG_INTERNET",
            "category": "INTERNET",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "Roke Telecom Internet",
            "code": "ROKE_TELECOM_UG_INTERNET",
            "category": "INTERNET",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "Tangerine Internet",
            "code": "TANGERINE_UG_INTERNET",
            "category": "INTERNET",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "UTL Internet",
            "code": "UTL_INTERNET",
            "category": "INTERNET",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "Airtel Uganda Internet",
            "code": "AIRTEL_UG_INTERNET",
            "category": "INTERNET",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "AZAM TV",
            "code": "AZAM_TV",
            "category": "TV",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "DSTV",
            "code": "DSTV",
            "category": "TV",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "GOtv",
            "code": "GO_TV",
            "category": "TV",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "Zuku TV",
            "code": "ZUKU_TV",
            "category": "TV",
            "has_price_list": false,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "StarTimes",
            "code": "STARTIMES_TV",
            "category": "TV",
            "has_price_list": false,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "National Water",
            "code": "NATIONAL_WATER",
            "category": "UTILITIES",
            "has_price_list": false,
            "has_choice_list": true,
            "billable": false
        },
        {
            "name": "UMEME PostPaid",
            "code": "UMEME_POST_PAID",
            "category": "UTILITIES",
            "has_price_list": false,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "UMEME PrePaid (Yaka)",
            "code": "UMEME_PRE_PAID",
            "category": "UTILITIES",
            "has_price_list": false,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "MTN Voice Bundles",
            "code": "MTN_UG_VOICE_BUNDLES",
            "category": "OTHERS",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        },
        {
            "name": "MTN Combo Bundles",
            "code": "MTN_UG_COMBO_BUNDLES",
            "category": "OTHERS",
            "has_price_list": true,
            "has_choice_list": false,
            "billable": false
        }
    ]
}

Response Parameters

Parameter Description
name Name of the product.
code Unique code to identify a product.
category Category for a product.
has_price_list Indicates whether a product has price packages for subscription.
has_choice_list Indicates whether a product has a support list of choice options for purchase.
billable Indicates whether Relworx charges you to purchase a product.

Price List

This API endpoint provides a price list for a product.

HTTP Request

Arguments

Parameter Type Required Description
code string Yes Product code.

Sample request to get price-list of a products.

Make sure to replace <--Your API Key--> with your generated API Key.

   curl -i -H "Accept: application/vnd.relworx.v2" -H "Content-Type: application/json" -H "Authorization: Bearer <--Your API Key-->" https://payments.relworx.com/api/products/price-list\?code\=MTN_UG_INTERNET

Sample response.

{
    "success": true,
    "price_list": [
        {
            "code": "MTN_UG_INTERNET:246624",
            "name": "MTN Data Night pack 1GB valid 12am - 6am",
            "price": 2000
        },
        {
            "code": "MTN_UG_INTERNET:246701",
            "name": "MTN Data Quarterly 10GB",
            "price": 75000
        },
        {
            "code": "MTN_UG_INTERNET:246702",
            "name": "MTN Data Quarterly 30GB",
            "price": 150000
        },
        {
            "code": "MTN_UG_INTERNET:246643",
            "name": "MTN Data Quarterly 3GB",
            "price": 30000
        },
        {
            "code": "MTN_UG_INTERNET:246622",
            "name": "MTN Data Daily 50MBs valid for 60Mins",
            "price": 500
        },
        {
            "code": "MTN_UG_INTERNET:246623",
            "name": "MTN Data Daily 1GB valid for 60Mins",
            "price": 5000
        },
        {
            "code": "MTN_UG_INTERNET:246628",
            "name": "MTN Data Weekly 500MBs",
            "price": 5000
        },
        {
            "code": "MTN_UG_INTERNET:246629",
            "name": "MTN Data Weekly1.5Gb",
            "price": 10000
        },
        {
            "code": "MTN_UG_INTERNET:246630",
            "name": "MTN Data Weekly 5GB",
            "price": 20000
        },
        {
            "code": "MTN_UG_INTERNET:246616",
            "name": "MTN Data Daily 15MBs 250",
            "price": 250
        },
        {
            "code": "MTN_UG_INTERNET:246617",
            "name": "MTN Data Daily 40MBs",
            "price": 500
        },
        {
            "code": "MTN_UG_INTERNET:246618",
            "name": "MTN Data Daily 100MBs",
            "price": 1000
        },
        {
            "code": "MTN_UG_INTERNET:246619",
            "name": "MTN Data Daily 300MBs",
            "price": 2000
        },
        {
            "code": "MTN_UG_INTERNET:246621",
            "name": "MTN Data Daily 700MBs",
            "price": 10000
        },
        {
            "code": "MTN_UG_INTERNET:246697",
            "name": "MTN Data Monthly 300MBs",
            "price": 5500
        },
        {
            "code": "MTN_UG_INTERNET:246620",
            "name": "MTN Data Daily 1GB",
            "price": 5000
        },
        {
            "code": "MTN_UG_INTERNET:246633",
            "name": "MTN Data Monthly 10GBs",
            "price": 50000
        },
        {
            "code": "MTN_UG_INTERNET:246634",
            "name": "MTN Data  Monthly 30GBs",
            "price": 100000
        },
        {
            "code": "MTN_UG_INTERNET:246635",
            "name": "MTN Data Monthly 100GBs",
            "price": 550000
        },
        {
            "code": "MTN_UG_INTERNET:246636",
            "name": "MTN Data Monthly 25MBs",
            "price": 1500
        },
        {
            "code": "MTN_UG_INTERNET:246698",
            "name": "MTN Data Monthly 600MBs",
            "price": 10000
        },
        {
            "code": "MTN_UG_INTERNET:246637",
            "name": "MTN Data Monthly 500MBs",
            "price": 20000
        },
        {
            "code": "MTN_UG_INTERNET:246699",
            "name": "MTN Data Monthly 2GB",
            "price": 20000
        }
    ]
}

Choice List

This API endpoint provides a choice list for a product.

HTTP Request

Arguments

Parameter Type Required Description
code string Yes Product code.

Sample request to get choice-list of a products.

Make sure to replace <--Your API Key--> with your generated API Key.

   curl -i -H "Accept: application/vnd.relworx.v2" -H "Content-Type: application/json" -H "Authorization: Bearer <--Your API Key-->" https://payments.relworx.com/api/products/choice-list\?code\=NATIONAL_WATER

Sample response.

{
    "success": true,
    "choice_list": [
        {
            "id": "249378",
            "name": "NWSC Mukono"
        },
        {
            "id": "249375",
            "name": "NWSC Entebbe"
        },
        {
            "id": "249376",
            "name": "NWSC Kawuku"
        },
        {
            "id": "249372",
            "name": "NWSC Iganga"
        },
        {
            "id": "249545",
            "name": "NWSC Lugazi"
        },
        {
            "id": "249373",
            "name": "NWSC Jinja"
        },
        {
            "id": "249374",
            "name": "NWSC Kajjansi"
        },
        {
            "id": "249371",
            "name": "NWSC Kampala"
        },
        {
            "id": "249379",
            "name": "Other NWSC Areas"
        }
    ]
}

Validate Product

This API endpoint validates a product. Product validation is required before every product purchase.

HTTP Request

Sample request for product validation.

Make sure to replace <--Your API Key--> with your generated API Key.


curl "https://payments.relworx.com/api/products/validate" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.relworx.v2" \
  -H "Authorization: Bearer <--Your API Key-->" \
  -d '{
        "account_no": "RELJH012BV45P",
        "reference": "52750b30ffbc7de3b36",
        "msisdn": "0701454887",
        "amount": 1000,
        "product_code": "MTN_UG_AIRTIME",
        "contact_phone": "0701454832",
    }'

Sample response.

{
    "success": true,
    "customer_name": "",
    "validation_reference": "416b358df57e82a6"
}

Arguments

Parameter Type Required Description
account_no string Yes Business account number. This is generated for you when you create a business account.
reference string Yes A unique generated string to identify your request. A minimum of 8 and maximum of 36 characters is allowed.
msisdn string Yes Product receiver account number. i.e Yaka / National water meter number.
amount decimal Yes Product purchase amount / price.
product_code string Yes Code for product.
contact_phone string Yes Contact phone number for on which SMS is sent after product purchase.
location_id string No Parameter is required for validating product code NATIONAL_WATER. Get this value from the choice-list of product with code NATIONAL_WATER.

Response Parameters

Parameter Description
customer_name Name of customer to receive product if available.
validation_reference A unique reference that identifies a validation. This is required when purchasing product.

Purchase Product

This API endpoint enables you to purchase a product.

HTTP Request

Sample request for product purchase.

Make sure to replace <--Your API Key--> with your generated API Key.


curl "https://payments.relworx.com/api/products/purchase" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.relworx.v2" \
  -H "Authorization: Bearer <--Your API Key-->" \
  -d '{
        "account_no": "RELJH012BV45P",
        "validation_reference": "416b358df57e82a6uyd"
    }'

Sample response.

{
    "success": true,
    "message": "Product purchase in progress.",
    "internal_reference": "ae84c6691c6b9706061b2f093d25ced5"
}

Arguments

Parameter Type Description
account_no string Business account code. This is generated for you when you create a business account.
validation_reference string Validation reference obtained during validation.

Webhooks

When the status of your request changes from pending to either failed or success, a POST request is sent to your configured webhook endpoint including details of your request after processing. You are required to acknowledge the webhook request by responding with a HTTP 200 OK, otherwise sending is retried 10 times with exponential backoff.

Sample Webhook payload:

{
  "status": "success",
  "message":  "Request payment completed successfully.",
  "customer_reference": "kemist656ehgvcd",
  "internal_reference": "fdd10a4c5d6b459d54ebc5f09d095101",
  "msisdn": "+256773454899",
  "amount": 500.0,
  "currency": "UGX",
  "provider": "mtn_mobile_money",
  "charge": 12.5
}

Authenticate Webhook Requests

Relworx signs webhook requests so you can (optionally) verify that requests are generated by Relworx and not a third-party pretending to be Relworx. If your application exposes sensitive data, you may want to be sure the requests are coming from Relworx. This isn't required, but offers an additional layer of verification.

Verifying Request Signatures

Relworx includes an additional HTTP header with webhook POST requests, Relworx-Signature, which will contain the signature for the request. To verify a webhook request, generate a signature using the same key that Relworx uses and compare that to the value of the Relworx-Signature header.

Get your webhook authentication key

When you create a business account, a key is automatically generated. You can also view and reset the key from the settings section on your business account view page.

Sample PHP implementation to generate verification signature:

/**
 * @param string $webhook_key the webhooks authentication key
 * @param string $url the webhook url
 * @param string $timestamp the signature timestamp
 * @param array $params the requests POST parameters
 */

//Only include these from POST data
$params = array(
  "status" => "success",
  "customer_reference" => "shdfjsue789sh8jshuehu",
  "internal_reference" => "jshfufehkshffkseuhfskahakhuefak",
);

function generateSignature($webhook_key, $timestamp, $url, $params) {
    $signed_data = $url;
    $signed_data .= $timestamp;
    ksort($params);
    foreach ($params as $key => $value) {
        $signed_data .= strval($key);
        $signed_data .= strval($value);
    }

    return hash_hmac('sha256', $signed_data, $webhook_key, false);
}

Generate a signature

In your code that receives or processes webhook requests:

  1. Create a string with the webhook's URL, exactly as you entered it (including any query strings, if applicable). Relworx always signs webhook requests with the exact callback URL you provided for your request. A difference as small as including or removing a trailing slash will prevent the signature from validating.

  2. Extract the timestamp and signature from the header. Relworx includes a timestamp in the Relworx-Signature header to mitigate replay attacks. A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload. Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and v corresponds to the signature. Sample Relworx-Signature "relworx-signature": "t=1561370460,v=fgrSxEFI/z6Twr6xZogRYnKCfew="

  3. Concatenate signature timestamp to webhook URL.

  4. Sort the request's POST variables alphabetically by key. Append each POST variable's key and value to the URL string, with no delimiter. Only include POST variables shown in sample code. status, customer_reference, internal_reference

  5. Hash the resulting string with HMAC-SHA256, using your webhook signing key to generate a hex-encoded signature.

  6. Compare the hex-encoded signature that you generated to the signature provided in the Relworx-Signature HTTP header.