Introduction

Welcome to WeCashUp , the new way of accepting Mobile Money payments

across Africa with one single integration. The WeCashUp API is based on the
REST architecture and uses the conventional HTTP response codes to indicate
responses returned by our API. Our architecture is highly secure, so to securely
interact with the WECASHUP API, all our partners must also secure the way they
use API resources. The API uses JSON data format for all responses. With
WeCashUp API, you can do the following CRUD operations:

J. Create.
K. Read.
L. Update.
M. Delete

To integrate WeCashUp on your application you will need to create an account. In

order to facilitate the discovery of API resources, we define two type of account.
TEST mode account for stating resources and LIVE mode account for production
resources.

It is very easy to get started with our API. Just follow the following steps:

J. Sign up to get API keys.

K. Setup the checkout page with credentials (HTML form or plugin setting
page of the CMS).
L. Use API resources in TEST mode.

To get LIVE credentials and get to production, you need to activate your account
by following instructions from the dashboard.

Authentification
To interact with the API, you need to be identified by providing your keys in each
request. There are two types of key, both in TEST and LIVE mode. Public key and
Secret key. You can find your keys in your dashboard. This is sensitive data. Be
careful not to communicate them to third parties. If you notice a misuse of your
keys, you have the ability to generate new ones in your dashboard.

To securely call API resources and avoid intrusion, all your request must be
in HTTPS, so all our partners must have an SSL Certificate installed on their
side.

Errors
JSON sample of erros you can get when calling API endpoint:

{
"response_details": "Bad Request",
"response_content": {},
"response_errors": {},
"response_code": 400,
"response_status": "failed"
}

{
"response_content": "Unauthorized",
"response_errors": "Authentification error ! Invalid SSL certificate (HTTPS) or i
"response_code": 401,
"response_status": "failed"
}

{
"response_details": "Not found",
"response_content": {},
"response_errors": {
"entity": "Not found"
},
"response_code": 404,
"response_status": "failed"
}

{
"response_details": "Unsupported Transaction Method",
"response_content": {},
"response_errors": {
"Unsupported": "Transaction method not supported."
},
"response_code": 501,
"response_status": "failed"
}

{
"response_details": "Invalid Parameters",
"response_content": {},
"response_errors": {
"transaction_sender_phone_number": "Invalid"
},
"response_code": 402,
"response_status": "failed"
}

WeCashUp uses conventional HTTP response codes to indicate the success or

failure of an API request. In general, codes in the 2xx range indicate successes,
codes in the 4xx range indicate errors caused by the information provided by the
user (e.g., a required parameter was omitted,etc.), and codes in the 5xx range
indicate an error with the WeCashUpâ​​ servers (what happens rarely).

However, not all errors map cleanly on to HTTP response codes. When a request
is valid but does not complete successfully (e.g., a Payment method not
allowed), we return a 402 error code.

Code Message Meaning

200 OK Response to a successful GET, PATCH or DELETE request.

MeaningResponse to a POST that results in a creation. Should

201 Created be combined with a Location header pointing to the location of
the new resource..

Response to a successful request that won't be returning a

204 No content
body (like a DELETE request).

304 Not modified Used when HTTP caching headers are in play.

400 Bad request The request is malformed, such as if the body does not parse.

When no or invalid authentication details are provided. Also

401 Unauthorized useful to trigger an auth popup if the API is used from a
browser.

Invalid
402 Happen when the value of a parameter is not correct.
Parameters

When authentication succeeded but authenticated user

403 Forbidden
doesn't have access to the resource.

404 Not found When a non-existent resource is requested.

Method not When an HTTP method is being requested that isn't allowed
405
allowed for the authenticated user.

Too Many
429 When a request is rejected due to rate limiting.
Request

500 Server Errors Something went wrong on WeCashUp's end. (These are rare).

Unsupported
Happen when try to proceed transaction with unknown
501 Transaction
method.
Method

Pagination
When you make API calls to retrieve resources, the volume of data can be very
large and increase response times. To compensate for this latency, it is strongly
recommended to set limits of result. Otherwise, the API will automatically set the
limit to the 1000 most recent requested items.

When a limit (e.g : limit = 100) is set, the API sends the requested items as well
as the index of the next elements (next=101) and the previous ones (prev=1).

limit: Define the number of elements you want to query and always return
the most recent elements. This parameter must be between 1 to 1000.
next: When calling API resources with limit or not, the API returns the result
and if there are more resources, it also adds the index for the next page.
prev: When the resources you are calling are between different pages, you
also get the next and the previous indexes.

Versioning
WeCashUp API continues to grow. We are continually improving and adding new
features to improve our services. Which implies to release updates to the API.
When releasing new version, we publish the change made to the API and the
impact it involves with our users. Our convention consiste to define version as
v1.0 for Version 1.0 for example. The current version is v2.0.

Integration
To integrate WeCashUp is very straightforward and involves you just adding a
payment button to your application. For the payment button to work you will
need to add 3 scripts to your code base. Lets see WeCashUp in action with the
demo below.

Test phone numbers

These numbers allows you to make a simulation of payment, by clicking the
button below Pay Now, it will be you ask for your phone number, you can then
use one of these numbers.

Country Area code Providers Phone number

Cameroon 00237 MTN Mobile Money 683 87 18 72

Orange Money 696 53 21 37

Ivory Coast 00225 MTN Mobile Money 75 13 70 86

Orange Money 89 51 04 50

Mali 00223 Orange 94 84 11 10

Malitel 96 17 34 32

Niger 00227 Airtel Money 99 25 08 54

Orange Money 80 80 19 41

Test card numbers

These card numbers allows you to test payment with credit card payment
method.

Providers Number Date CVV

VISA 4012 0010 3714 1112 12/18 123

Mastercard 5476 8520 5684 3079 12/18 123

Demo
You can try the following demo to see how simple it is to pay with WeCashUp:

How it works?
At this point, you have seen how it is simple to process a payment with
WeCashUp. So, now, let's dive inside the payment process.

For security reasons, sensitive data from your customers never passes
through your server (PIN codes etc.). WeCashUp takes care of the security
on its server, you just have to enable HTTPS on your payment page by
getting an SSL certificate.

The diagram below explains the payments process end to end in detail. How
WeCashUp works and how to integrate it into your application.

What does it means ?

The Callback script is used for the confirmation. You can adapt it regardless
of your programming language.

<?php

header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, POST');

$merchant_uid = 'YOUR_MERCHANT_UID'; // Replace with your merchant_uid

$merchant_public_key = 'YOUR_MERCHANT_PUBLIC_KEY'; // Replace with your merchant_public_k
$merchant_secret = 'YOUR_MERCHANT_SECRET'; // Replace with your mer
$transaction_uid = '';// create an empty transaction_uid
$transaction_token = '';// create an empty transaction_token
$transaction_provider_name = ''; // create an empty transaction_provider_name
$transaction_confirmation_code = ''; // create an empty confirmation code
if(isset($_POST['transaction_uid'])){
$transaction_uid = $_POST['transaction_uid']; // Get the transaction_uid posted by the pa
}
if(isset($_POST['transaction_token'])){
$transaction_token = $_POST['transaction_token']; // Get the transaction_token posted by
}
if(isset($_POST['transaction_provider_name'])){
$transaction_provider_name = $_POST['transaction_provider_name']; // Get the transaction
}
if(isset($_POST['transaction_confirmation_code'])){
$transaction_confirmation_code = $_POST['transaction_confirmation_code']; // Get the tra
}
$url = 'https://www.wecashup.com/api/v2.0/merchants/'.$merchant_uid.'/transactions/'

echo $url;

//Steps 7 : You must complete this script at this to save the current transaction in your
/* Provide a table with at least 5 columns in your database capturing the following
/ transaction_uid | transaction_confirmation_code| transaction_token| transaction_provid

//Step 8 : Sending data to the WeCashUp Server

$fields = array(
'merchant_secret' => urlencode($merchant_secret),
'transaction_token' => urlencode($transaction_token),
'transaction_uid' => urlencode($transaction_uid),
'transaction_confirmation_code' => urlencode($transaction_confirmation_code),
'transaction_provider_name' => urlencode($transaction_provider_name),
'_method' => urlencode('PATCH')
);
foreach($fields as $key=>$value) { $fields_string .= $key.'='.$value.'&'; }
rtrim($fields_string, '&');
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST, count($fields));
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

//Step 9 : Retrieving the WeCashUp Response

$server_output = curl_exec ($ch);

echo $server_output;

curl_close ($ch);

$data = json_decode($server_output, true);

if($data['response_status'] =="success"){

echo '<br><br> response_code : '.$data['response_code'];

}else{
echo '<br><br> response_code : '.$data['response_code'];
}
?>

This script can be found in the WeCashUp Github repository

J. Copy the source code found on the HTML tab on the right and paste to the
payment page where you would like the “Pay” to appear. This code
automatically calls MobileMoney.js library. If you don't have an SSL certificat
on your site, you can not call the library.

K. This library displays the “Pay” button on your checkout page. Note that you
can pre-fill the data-sender-phonenumber attribute with your customerʼs
phone number.

L. The customer will get to your page and select the option “Pay” , they will
receive different payment options “Cash”, “Telecom”, “M-Wallet”, “Card” or
“Crypto”. Enter their mobile phone number and then click on the
confirmation button to start the processing of the payment (e.g “Pay 100
XAF”).

M. The payment details are securely sent directly to WeCashUpʼs server from
the client browser via a HTTP Ajax Request. This is successful only if the
basic validations pass.

j. WeCashUp processes all the data sent and returns a “transaction_token”, a

“transaction_uid”, and the “list of providers” available in the customerʼs
country. In case of “Telecom” payment, WeCashUp is able to detect the
customerʼs operator from the mobile phone number provided and will then
provide payment instructions to complete the transaction and receive
confirmation code from Telecom Operators. The confirmation code will then
be used by the customer to confirm the payment. In case of “Cash”, “M-
Wallet”, “Card” or “Carypto” there's no need of confirmation code. Payment
instructions are going to be display and send to the customer by SMS.

l. After receiving that code, the customer must input the code in the checkout
page and click on “Confirm” to validate the payment. All this transaction
information which includes provider name, confirmation code and all the
other information provided will be send to the WeCashUp Server via the
Callback script. (Remember you will be required to share the callback url:
this is an absolute link to the script that is provided by you on the
WeCashUp Merchant Dashboard, or directly at the level of FORM ACTION =
‘merchant_callback_urlʼ of the first script, which you copied in the stage 1 in
your right).

n. It the Callback script, you need to store in your database all the information
sent by the API and the confirmation code input from the customer for your
own record history.

o. To perform step 8 you will need to initialize and add the API Credentials that
you are assigned once you sign up on WeCashUp. this is the (merchant_uid,
merchant_public_key and merchant_secret). and then you will need to send
the following 4 values(transaction_uid, transaction_token,
transaction_provider_name and merchant_secret) to WeCashUpʼs server via
a POST request. Kindly note it will be very important that this request have
the variable _method assigned the value “PATCH”.Currently you can get the
php version of the callback.php on the right tab assignment PHP . You can
copy paste the code and use it . It is commented out to help you understand
it better. (Feel free to adapt it to your language of preference, we will be
sharing more versions of the script in other languages.)

s. The API will send you a success response with the transaction payload or a
failure response with errors payload.

Jt. You will be required to save this details that have been provided to your
database since you will use them later.

JJ. You will then need to redirect the customer to a successful or failure page
depending on the response send by the API.

JK. The provider will send us a confirmation message showing whether or not
the money was received. For the CASH payment in a maximum delay of
48h(For the other payment methods it happens instantly). This
communication between WeCashUp and your server is done through
default_webhook.php (You can download a copy of this on
default_webhook.zip or paste the code from the right tab tagged PHP. You
can also adapt the script to a language that matches your stack . We are
currently working on ensuring to have your favorite languages here ).
WeCashUp will POST the following to your webhook script
(merchant_secret,transaction_uid, transaction_token,transaction_type
transaction_status and transaction_details)

JL. The Merchant shall verify that the information received from WeCashUp .
This is done by checking that the transaction_uid , transaction_token ,
merchant_secret corresponds to a previously saved entry in step 7 and 10.
Note that WeCashUp is the only system that knows the merchant_secret .
With this you will be able to verify that the final request is coming from
WeCashUp and not another system trying to acte as WeCashUp.

JM. If all the information received corresponds with the verified information in
Step 13, the merchant must retrieve the status of the transaction(PENDING,
TOVALIDATE, REFUNDED) and complete the transaction.

Jj. The merchant can now inform the customer that the transaction was
successful and now can proceed with the relevant call to action depending
on the context of the Merchant. (E.g in an e-commerce site this may trigger
a delivery once confirmation of payment is done.)

MAIN RESOURCES
Resources are core elements of WeCashUp API. They allow you to perform all
necessary operations to a great user experience.

Merchants
WeCashUp works with several partners (Regulators, Telecom operators, Banks,
Acquires, PSP, e-merchants, etc…). These partners are defined as Merchants in
WeCashUp ecosystem. The result is that we have different type of merchants.
Merchants entities are the most high entities in WeCashUp API. It allows users to
create a merchant account.

The merchant object represents the legal representative of an account. However,

a merchant account can have others merchant entity linked in a team. It contains
the following parameters :

name type comments

merchant_uid String The unique ID assigned to the merchant.

merchant_public_key String The API public Key assigned to the merchant.

The API private Key assigned to the

merchant_private_key String
merchant.

The primary merchant business email

merchant_email String
address.

The publicly visible name of the merchant

merchant_legal_name String
business.

The country where the merchant business is

merchant_country String
localized.

The town where the merchant business is

merchant_town String
localized.

The zip code where the merchant business is

merchant_postcode String
localized.

The physical address where the merchant

merchant_physical_address String
business is localized.

The currency this merchant has chosen to

merchant_currency String
use as the default.

merchant_phone_number String The primary merchant contact number.

The merchant execution mode (TEST or

merchant_execution_mode String
LIVE).

The category of the merchant (Individual or

merchant_category String
Company).

The merchant type in WeCashUp

merchant_type String
Environnement.

merchant_website String The merchant official website.

The merchant status in WeCashUp

merchant_status String
Environnement.

merchant_activity_area String The business area of the merchant business.

VAT identification number of the merchant

merchant_vat_number String
business.

The registration number of the merchant

merchant_registration_number String
business.

merchant_legal_status String The merchant business legal status.

merchant_bank_iban_number String The merchant business IBAN number.

The merchant business bank account

merchant_bank_country String
country.

The default webhook url to update the

merchant_default_webhook_url String
merchant.

The merchant default callback url to be used

merchant_callback_url String if a there no one in the transaction
processing.

The payment method authorized by

merchant_payment_method list
WeCashUp for the merchant account.

Create a merchant account

Request:

Response:

{
"response_details": "List of requested merchants",
"response_content": {
"merchants": [
{
"merchant_email": "[email protected]",
"merchant_uid": "TeslaMYMopkQ0fOl9cty9dVq1",
"merchant_public_key": "opkQ0fOl9cty9dVq1pkt",
"merchant_secret": "tp8g0fOl9ct53Azr1skt",
"merchant_last_edit_date": "23 oct. 2017 09:47:41 GMT",
"merchant_verified": "false",
"merchant_status": "INCOMPLETE",
"merchant_mode": "TEST",
"merchant_legal_name": "Tesla",
"merchant_country": "FR"
}
]
},
"response_errors": {},
"response_code": 201,
"response_status": "OK"
}

To create a merchant account, you must send a request to the API endpoint with
some required parameters :

Method : POST
Content-Type: application/x-www-form-urlencoded
Endpoint : https://www.wecashup.com/api/v2.0/merchants
Payload:
merchant_email : “[email protected]”
merchant_password : “ABCDEFG123456”
merchant_legal_name : “Tesla”
merchant_country : “FR”

If the request succeed, the API returns a merchant account in a json object with
some additional parameters as in the sample at right: