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:
- Create.
- Read.
- Update.
- 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:
- Sign up to get API keys.
- Setup the checkout page with credentials (HTML form or plugin setting page of the CMS).
- 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.
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 invalid merchant credentials.",
"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. |
201 | Created | MeaningResponse to a POST that results in a creation. Should be combined with a Location header pointing to the location of the new resource.. |
204 | No content | Response to a successful request that won't be returning a 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. |
401 | Unauthorized | When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser. |
402 | Invalid Parameters | Happen when the value of a parameter is not correct. |
403 | Forbidden | When authentication succeeded but authenticated user doesn't have access to the resource. |
404 | Not found | When a non-existent resource is requested. |
405 | Method not allowed | When an HTTP method is being requested that isn't allowed for the authenticated user. |
429 | Too Many Request | When a request is rejected due to rate limiting. |
500 | Server Errors | Something went wrong on WeCashUp's end. (These are rare). |
501 | Unsupported Transaction Method | Happen when try to proceed transaction with unknown 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 |
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.
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 ?
<form action="https://www.wecashup.cloud/cdn/tests/websites/PHP/callback_lucas.php" method="POST" id="wecashup">
<script async src="https://www.wecashup.com/library/MobileMoney.js" class="wecashup_button"
data-demo
data-sender-lang="en"
data-sender-phonenumber="+237671234567"
data-receiver-uid="EvIvZFlBKNaMddjXJOOpEWNeWj52"
data-receiver-public-key="kCAc2vOwcANrbdKCuFnXLhS76yMx3f8iUytCbN8Drx6T"
data-transaction-parent-uid=""
data-transaction-receiver-total-amount="594426"
data-transaction-receiver-reference="XVT2VBF"
data-transaction-sender-reference="XVT2VBF"
data-sender-firstname="Test"
data-sender-lastname="Test"
data-transaction-method="pull"
data-image="https://storage.googleapis.com/wecashup/frontend/img/airfrance.png"
data-name="Air France"
data-crypto="true"
data-cash="true"
data-telecom="true"
data-m-wallet="true"
data-split="true"
configuration-id="3"
data-marketplace-mode="false"
data-product-1-name="Billet ABJ PRS"
data-product-1-quantity="1"
data-product-1-unit-price="594426"
data-product-1-reference="XVT2VBF"
data-product-1-category="Billeterie"
data-product-1-description="France is in the Air"
>
</script>
</form>
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_key !!!
$merchant_secret = 'YOUR_MERCHANT_SECRET'; // Replace with your merchant_private_key !!!
$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 payment box
}
if(isset($_POST['transaction_token'])){
$transaction_token = $_POST['transaction_token']; // Get the transaction_token posted by the payment box
}
if(isset($_POST['transaction_provider_name'])){
$transaction_provider_name = $_POST['transaction_provider_name']; // Get the transaction_provider_name posted by the payment box
}
if(isset($_POST['transaction_confirmation_code'])){
$transaction_confirmation_code = $_POST['transaction_confirmation_code']; // Get the transaction_confirmation_code posted by the payment box
}
$url = 'https://www.wecashup.com/api/v2.0/merchants/'.$merchant_uid.'/transactions/'.$transaction_uid.'?merchant_public_key='.$merchant_public_key;
echo $url;
//Steps 7 : You must complete this script at this to save the current transaction in your database.
/* Provide a table with at least 5 columns in your database capturing the following
/ transaction_uid | transaction_confirmation_code| transaction_token| transaction_provider_name | transaction_status */
//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"){
//Do wathever you want to tell the user that it's transaction succeed or redirect him/her to a success page
$location = 'https://www.wecashup.cloud/cdn/tests/websites/PHP/responses_pages/success.html';
}else{
//Do wathever you want to tell the user that it's transaction failed or redirect him/her to a failure page
$location = 'https://www.wecashup.cloud/cdn/tests/websites/PHP/responses_pages/failure.html';
}
//redirect to your feedback page
echo '<script>top.window.location = "'.$location.'"</script>'
?>
This script can be found in the WeCashUp Github repository
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.
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.
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”).
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.
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.
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).
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.
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.)
The API will send you a success response with the transaction payload or a failure response with errors payload.
You will be required to save this details that have been provided to your database since you will use them later.
You will then need to redirect the customer to a successful or failure page depending on the response send by the API.
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)
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.
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.
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. |
merchant_private_key | String | The API private Key assigned to the merchant. |
merchant_email | String | The primary merchant business email address. |
merchant_legal_name | String | The publicly visible name of the merchant business. |
merchant_country | String | The country where the merchant business is localized. |
merchant_town | String | The town where the merchant business is localized. |
merchant_postcode | String | The zip code where the merchant business is localized. |
merchant_physical_address | String | The physical address where the merchant business is localized. |
merchant_currency | String | The currency this merchant has chosen to use as the default. |
merchant_phone_number | String | The primary merchant contact number. |
merchant_execution_mode | String | The merchant execution mode (TEST or LIVE). |
merchant_category | String | The category of the merchant (Individual or Company). |
merchant_type | String | The merchant type in WeCashUp Environnement. |
merchant_website | String | The merchant official website. |
merchant_status | String | The merchant status in WeCashUp Environnement. |
merchant_activity_area | String | The business area of the merchant business. |
merchant_vat_number | String | VAT identification number of the merchant business. |
merchant_registration_number | String | The registration number of the merchant business. |
merchant_legal_status | String | The merchant business legal status. |
merchant_bank_iban_number | String | The merchant business IBAN number. |
merchant_bank_country | String | The merchant business bank account country. |
merchant_default_webhook_url | String | The default webhook url to update the merchant. |
merchant_callback_url | String | The merchant default callback url to be used if a there no one in the transaction processing. |
merchant_payment_method | list | The payment method authorized by WeCashUp for the merchant account. |
Create a merchant account
Request:
curl "https://www.wecashup.com/api/v2.0/merchants" \
-d "merchant_email: [email protected]" \
-d "merchant_legal_name: Tesla" \
-d "merchant_password: ABCDEFG123456"\
-d "merchant_country: FR"
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”
- merchant_email :
If the request succeed, the API returns a merchant account in a json object with some additional parameters as in the sample at right:
Retrieve a merchant account
Request:
curl "https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>" \
-d "merchant_public_key: opkQ0fOl9cty9dVq1pkt" \
-d "merchant_secret: tp8g0fOl9ct53Azr1skt"
Response:
{
"response_details": "List of requested merchants",
"response_content": {
"merchants": [
{
"merchant_email": "[email protected]",
"merchant_uid": "TeslaMYMopkQ0fOl9cty9dVq1",
"merchant_last_edit_date": "23 oct. 2017 09:47:41 GMT",
"merchant_verified": "true",
"merchant_status": "INCOMPLETE",
"merchant_mode": "TEST",
"merchant_legal_name": "Tesla",
"merchant_country": "FR"
}
]
},
"response_errors": {},
"response_code": 200,
"response_status": "OK"
}
To get details about a merchant account, you must send a request to the API endpoint with the following parameters :
- Method :
GET
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- merchant_secret :
tp8g0fOl9ct53Azr1skt
- merchant_public_key :
Update a merchant account
Request:
curl "https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>" \
-d "merchant_email: [email protected]" \
-d "merchant_legal_name: Tesla" \
-d "merchant_password: ABCDEFG123456"\
-d "merchant_country: FR" \
-d "_method: PATCH"
Response:
{
"response_details": "List of requested merchants",
"response_content": {
"merchants": [
{
"merchant_website": "https://www.tesla.com",
"merchant_email": "[email protected]",
"merchant_phone_numbber": "003361234567",
"merchant_uid": "TeslaMYMopkQ0fOl9cty9dVq1",
"merchant_last_edit_date": "23 oct. 2017 09:47:41 GMT",
"merchant_currency": "EUR",
"merchant_verified": "true",
"merchant_status": "ACTIVE",
"merchant_legal_name": "Tesla",
"merchant_country": "FR"
}
]
},
"response_errors": {},
"response_code": 201,
"response_status": "OK"
}
You can change some parameters in your merchant account by requesting the API with the necessary parameters. If you don’t provide somes parameters in your payload, those parameters are going to be unchanged in your account.
To update your account parameters, you must send a request to the API endpoint with the following parameters :
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- merchant_secret :
tp8g0fOl9ct53Azr1skt
- _method :
PATCH
- merchant_website :
https://www.tesla.com
- merchant_currency :
EUR
- merchant_phone_numbber :
003361234567
- merchant_public_key :
If the request succeeded, the API returns a merchant account in a json object just like at right:
However, for some parameters to be updated, you must send us a demand directly in your merchant dashboard.
Delete a merchant account
Deleting an account is a delicate operation. So you must be careful when deleting an account. To delete your account, you must send a request to the API endpoint with the following parameters :
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- merchant_secret :
tp8g0fOl9ct53Azr1skt
- _method :
DELETE
- merchant_public_key :
Customers
Customers are entities that will allow merchants to store its users through the API. A customer object is related to a merchant. However, different merchants can have the same customer, WeCashUp API is going to create one customer for each merchants.
Customer object in WeCashUp environnement is designated as transaction sender and contains the following parameters:
name | type | comments |
---|---|---|
transaction_sender_uid | String | The unique identifier of customer assign by WeCashUp. |
transaction_sender_phone_number | String | The phone number of the customer. |
transaction_sender_email | String | The email address of the customer. |
transaction_sender_firstname | String | The first name of the customer. |
transaction_sender_lastname | String | The last name of the customer. |
transaction_sender_birthdate | String | The birth date of the customer. |
transaction_sender_currency | String | The main currency of the customer. |
transaction_sender_shipping_country_code_iso2 | String | The shipping country of the customer. |
transaction_sender_shipping_town | String | The shipping town of the customer. |
transaction_sender_shipping_postcode | String | The shipping zip code of the customer. |
transaction_sender_billing_country_code_iso2 | String | The billing country of the customer. |
transaction_sender_billing_town | String | The billing town of the customer. |
transaction_sender_billing_postcode | String | The billing zip code of the customer. |
transaction_sender_others | list | Some additional parameters |
Create a customer
Request:
curl "https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/customers" \
-d "merchant_public_key: opkQ0fOl9cty9dVq1pkt" \
-d "merchant_secret: tp8g0fOl9ct53Azr1skt" \
-d "transaction_sender_phone_number: +237683870000" \
-d "transaction_sender_email: [email protected]" \
-d "transaction_sender_currency: XAF" \
-d "transaction_sender_firstname: Musk" \
-d "transaction_sender_lastname: John" \
-d "transaction_sender_shipping_country_code_iso2: CM" \
-d "transaction_sender_billing_country_code_iso2: CM" \
-d "transaction_sender_shipping_town: Douala" \
-d "transaction_sender_billing_town: Douala"
Response:
{
"response_details": "List of requested customers",
"response_content": {
"customers": [{
"merchant_uid": "EvIvZFlBKNaMddjXJOOpEWNeWj52",
"customer_uid": "6317033505725406952",
"customer_email": "[email protected]",
"customer_currency": "XAF",
"date": "22 Sep 2017 16:35:55 GMT",
"customer_firstname": "Musk",
"customer_lastname": "John",
"customer_shipping_country_code_iso2": "CM",
"customer_shipping_town": "Douala",
"customer_balance": "0.0",
"customer_billing_country_code_iso2": "CM",
"customer_status": "ACTIVE",
"customer_billing_town": "Douala",
"customer_phone_number": "+237683870000"
}
]
},
"response_errors": {},
"response_code": 200,
"response_status": "OK"
}
To create a customer, 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/<MERCHANT_UID>/customers
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- merchant_secret :
tp8g0fOl9ct53Azr1skt
- customer payload
- merchant_public_key :
Retrieve a customer
Response:
{
"response_details": "List of requested customers",
"response_content": {
"customers": [{
"merchant_uid": "EvIvZFlBKNaMddjXJOOpEWNeWj52",
"customer_uid": "6317033505725406952",
"customer_email": "[email protected]",
"customer_currency": "XAF",
"date": "22 Sep 2017 16:35:55 GMT",
"customer_firstname": "Musk",
"customer_lastname": "John",
"customer_shipping_country_code_iso2": "CM",
"customer_shipping_town": "Douala",
"customer_balance": "0.0",
"customer_billing_country_code_iso2": "CM",
"customer_status": "ACTIVE",
"customer_billing_town": "Douala",
"customer_phone_number": "+237683870000"
}
]
},
"response_errors": {},
"response_code": 200,
"response_status": "OK"
}
To retrieve a customer, you must send a request to the API endpoint with your credentials :
- Method :
GET
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/customers/<CUSTOMER_UID>
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- merchant_secret :
tp8g0fOl9ct53Azr1skt
- merchant_public_key :
You can also retrieve the list of your customers with one request. To do that, you just have to send a GET request to :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/customers
Update a customer
To update your customer parameters, you must send a request to the API endpoint with the following parameters :
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/customers/<CUSTOMER_UID>
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- merchant_secret :
tp8g0fOl9ct53Azr1skt
- _method :
PATCH
- customer payload
- merchant_public_key :
You get the JSON answer with the new paramters.
Delete a customer
To delete a customer, you must send a request to the API endpoint with the following parameters :
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/customers/<CUSTOMER_UID>
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- merchant_secret :
tp8g0fOl9ct53Azr1skt
- _method :
DELETE
- merchant_public_key :
Transactions
When it come to collect or send money from or to senders, transactions entities are created. Transactions are used to save payment parameters. To create transactions, there must be a valid merchant, sender and at least one product. If the sender doesn’t exist, the API create a new sender.
Transactions objects are composed with severals attributes that allow to define the kinds of actions to process. There are 4 types of transactions:
- Payment: This type allows merchant to accept pay in from there sender and from different payment channel.
- Refund: When a payment is disputed by a sender and you need then to refund the sender, a transaction of type Refund must be created.
- Transfer: A transfer transaction is created when you move fund from your WeCashUp account to your bank account or other type of account. To create a transfer transaction, be sure to have enough revenue in your WeCashUp Account.
- Balance: A balance transaction is created when there is a pay in or pay out transaction. Balance object represent the current amount of money available in your WeCashUp account.
A transaction can contains the following parameters:
name | type | comments |
---|---|---|
transaction_receiver_uid | String | The unique identifier of the receiver assign by WeCashUp. |
transaction_receiver_callback_url | String | The callback url to be used in the transaction. |
transaction_receiver_webhook_url | String | The webhook url to be used in the transaction in order to notify the merchant.. |
transaction_receiver_execution_mode | String | The execution mode of the transaction (TEST or LIVE). Depend on the credentials used. |
transaction_receiver_lang | String | The language of the receiver. (EN, FR, etc.). |
transaction_receiver_phone_number | String | The phone number of the receiver. |
transaction_receiver_email | String | The email address of the receiver. |
transaction_receiver_firstname | String | The first name of the receiver. |
transaction_receiver_lastname | String | The last name of the receiver. |
transaction_receiver_birthdate | String | The birth date of the receiver. |
transaction_receiver_currency | String | The main currency of the receiver. |
transaction_receiver_shipping_country_code_iso2 | String | The shipping country of the receiver. |
transaction_receiver_shipping_town | String | The shipping town of the receiver. |
transaction_receiver_shipping_postcode | String | The shipping zip code of the receiver. |
transaction_receiver_billing_country_code_iso2 | String | The billing country of the receiver. |
transaction_receiver_billing_town | String | The billing town of the receiver. |
transaction_receiver_billing_postcode | String | The billing zip code of the receiver. |
transaction_receiver_others | list | Some additional parameters |
transaction_parent_uid | String | The identifier of a parent transaction in case of split payment. |
transaction_sender_reference | String | The reference of the sender in merchant context. |
transaction_receiver_reference | String | The reference of the receiver in his own context. |
transaction_receiver_total_amount | Double | The transaction amount the receiver must receive in his currency. |
transaction_conversion_rates_folder | Double | The folder of the rate used to process the transaction. |
transaction_sender_total_amount | Double | The transaction amount the sender must send in his currency. |
transaction_sender_splitted_amount | Double | The part of the total amount the main sender must paid in case of split payment. |
transaction_type | String | The transaction type (payment, transfer, refund, and balance). |
transaction_provider_mode | String | The payment channel the sender is going to use to complete the transaction (mobile-money, airtime, wallet, cash, card or crypto. |
transaction_invites | list | The list of the invited people in case of split payment. |
transaction_sender_uid | String | The unique identifier of the sender assign by WeCashUp. |
transaction_sender_lang | String | The language of the sender. (EN, FR, etc.). |
transaction_sender_phone_number | String | The phone number of the sender. |
transaction_sender_email | String | The email address of the sender. |
transaction_sender_firstname | String | The first name of the sender. |
transaction_sender_lastname | String | The last name of the sender. |
transaction_sender_birthdate | String | The birth date of the sender. |
transaction_sender_currency | String | The main currency of the sender. |
transaction_sender_shipping_country_code_iso2 | String | The shipping country of the sender. |
transaction_sender_shipping_town | String | The shipping town of the sender. |
transaction_sender_shipping_postcode | String | The shipping zip code of the sender. |
transaction_sender_billing_country_code_iso2 | String | The billing country of the sender. |
transaction_sender_billing_town | String | The billing town of the sender. |
transaction_sender_billing_postcode | String | The billing zip code of the sender. |
transaction_sender_others | list | Some additional parameters |
transaction_uid | String | The unique identifier of the transaction set by the API. |
transaction_confirmation_code | String | The confirmation code of the transaction provide by Telecom operators in some case. |
transaction_token | String | The token set by the API in order to secure the transaction. |
transaction_provider_name | String | The name of the provider use to process the transaction. |
transaction_status | String | The status of a transaction (PENDING, PAID, FAILED, REFUNDED, etc.). |
transaction_others | list | Others details regarding the transaction. |
transaction_paid_date | Date | The date of the effective payment of the transaction. |
transaction_method | String | The method to be use to process the transaction (Push or Pull). |
transaction_marketplace_mode | Boolean | When the merchant is in Marketplace mode, this attribute must be set at “true”. |
Note: In case of a Pay in transaction (Pull), the merchant is the receiver and the customer is the receiver. In the opposite case, the merchant in the sender and the customer the receiver.
Create a transaction
To create a transaction, 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/<MERCHANT_UID>/transactions
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- transaction payload
- merchant_public_key :
Retreive a transaction
To get details about a transaction, you must send a request to the API endpoint with the following parameters :
- Method :
GET
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/transactions/<TRANSACTION_UID>
- Payload:
- merchant_public_key :
pk_test_opkQ0fOl9cty9dVq1pkt
- merchant_secret :
sk_test_opkQ0fOl9cty9dVq1pkt
- merchant_public_key :
Update a transaction
To update a transaction, you must authentification you request with your public and secret key. Any parameters not provided will be left unchanged.
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/transactions
- Payload:
- merchant_public_key :
pk_test_opkQ0fOl9cty9dVq1pkt
- merchant_secret :
sk_test_opkQ0fOl9cty9dVq1pkt
- _method :
PATCH
- merchant_public_key :
However, some parameters such a transaction_status, transaction_execution_mode, etc… can not be changed once set.
Delete a transaction
The WeCashUp environment does not allow you to delete a transaction.
Products
Product payload sample :
{
"transaction_product_data": [{
"product_1": {
"name": "Citroen C3",
"quantity": "1",
"unit_price": "10000",
"category": "voitures",
"reference": "XVT2VBF",
"description": "vroumvroum"
},
"product_2": {
"name": "Tesla 3",
"quantity": "1",
"unit_price": "30000",
"category": "voitures",
"reference": "XVT2VBF",
"description": "vroumvroum"
}
}]
}
Products are entities used to store goods or services sell by the merchant.
A product contains the following parameters:
name | type | comments |
---|---|---|
name | String | The name of your product. |
type | String | The type of your product (Good or Service). |
category | String | The category of your product. |
unit_price | double | The unit price of your product in your currency. |
quantity | int | The quantity of your product. |
description | String | Comments about your product. |
When you create a transaction, you must send product into a JSON object like the sample at the right:
Create a product
To create a product, 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/<MERCHANT_UID>/products
- Payload:
- merchant_public_key :
pk_test_opkQ0fOl9cty9dVq1pkt
- merchant_secret :
sk_test_opkQ0fOl9cty9dVq1pkt
- transaction_product_data
- product_1:
- name
- quantity
- unit_price
- category
- reference
- description
- product_1:
- merchant_public_key :
Retrieve a product
To get details about a product, you must send a request to the API endpoint with the following parameters :
- Method :
GET
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/products/<PRODUCT_UID>
- Payload:
- merchant_public_key :
opkQ0fOl9cty9dVq1pkt
- merchant_secret :
opkQ0fOl9cty9dVq1pkt
- merchant_public_key :
Update a product
To update a product, you must send a request to the API endpoint with the following parameters :
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/products/<PRODUCT_UID>
- Payload:
- merchant_public_key :
pk_test_opkQ0fOl9cty9dVq1pkt
- merchant_secret :
sk_test_opkQ0fOl9cty9dVq1pkt
- _method :
PATCH
- transaction_product_data
- product_1:
- name
- quantity
- unit_price
- category
- reference
- description
- product_1:
- merchant_public_key :
Delete a product
To delete a product, you must send a request to the API endpoint with the following parameters :
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/products/<PRODUCT_UID>
- Payload:
- merchant_public_key :
pk_test_opkQ0fOl9cty9dVq1pkt
- merchant_secret :
sk_test_opkQ0fOl9cty9dVq1pkt
- _method : 'DELETE'
- merchant_public_key :
Conversion rates
Conversionrate from XAF to all other Currencies sample:
{
"query": {
"count": 70,
"created": "2017-11-01T19:48:24Z",
"lang": "en-US",
"results": {
"rate": [{
"id": "XAFAOA",
"Name": "XAF/AOA",
"Rate": "0.2928",
"Date": "11/1/2017",
"Time": "7:45pm",
"Ask": "0.2957",
"Bid": "0.2928"
},
{
"id": "XAFBIF",
"Name": "XAF/BIF",
"Rate": "3.0867",
"Date": "11/1/2017",
"Time": "7:45pm",
"Ask": "3.1222",
"Bid": "3.0867"
},
...
]
}
}
}
WeCashUp API fetches in real time from accurate financial sources to get the right conversion rate, in order to process cross-currencies transactions.
When you want to process a transaction with using WeCashUp Javascript library, you must send a request to the API to the the right conversion rate :
- Method :
GET
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/rates
- Payload:
- merchant_public_key :
pk_test_opkQ0fOl9cty9dVq1pkt
- merchant_secret :
sk_test_opkQ0fOl9cty9dVq1pkt
- merchant_currency :
Currency
- merchant_public_key :
Note: if you use an old conversion rate, the transaction could fail.
To get the corresponding rate when executing a transaction, you must send the following request first:
- Method :
GET
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/rates
- Payload:
- merchant_public_key :
pk_test_opkQ0fOl9cty9dVq1pkt
- merchant_secret :
sk_test_opkQ0fOl9cty9dVq1pkt
- from :
A
- to :
B
- merchant_public_key :
The API is going to respond with the exact exchange rate.
Webhooks
WeCashUp API use webhooks notifications to update merchants about event that occurs in the payment process and can affect customers experiences. Instead of obliging merchants to check if an important event happens by pulling the API, we automatically push relevant notification to merchants application.
In your merchant dashboard, you can create as much as you need. For example, for a paid transaction, a suspicious transaction, a dispute, etc...
Payment Channels
WeCashUp API support many kind of payment channels, allowing the merchant to expand his market all over the world.. Integrating WeCashUp API allows you to offers to your customers many different ways to pay online.
Some payment methods are only available to certain geographic areas and others are allowed only when the merchant fulfill certain conditions
Cash
Cash payment allow the merchant to accept transaction to be paid by cash. We work with financial providers who give us the possibility to allow merchant to accept liquid payment for a good or service. Cash payments are available in all BCEAO and BEAC countries we cover.
To process a Cash payment, merchant need to create a transaction with the parameter transaction_provider_mode
set to cash
in the transaction payload.
Mobile Money
In most African countries, telecom operators offer Mobile Money solutions to their customers. Which offers to customers the possibility to possess a mobile wallet for their daily use. Mobile Money payment is a push-based method, which means your customer must take action to send the required amount in their currency to you by following API instruction.
To process a Mobile Money payment, merchant need to create a transaction with the parameter transaction_provider_mode
set to telecom
in the transaction payload.
Bank Wallet
With Mobile payments expanding, several banks are following the trend by developing mobile wallets for mobile applications all other the world. This allows them to offer new products to their existing customers while offering this service to new customers.
To process a Bank Wallets payment, merchant need to create a transaction with the parameter transaction_provider_mode
set to m-wallet
in the transaction payload.
Cryptocurrencies
Cryptocurrency like Bitcoin is secure money for the internet payment. You can pay without handing out sensitive financial information. It is a push-based payment method, which means you have absolute control over your wallet. Severals financials institutions accept cryptocurrencies to fastly process transactions all around the world.
To process a Cryptocurrencies payment, merchant need to create a transaction with the parameter transaction_provider_mode
set to crypto
in the transaction payload.
Merchant who want to accept cryptocurrencies payment can receive their money in there own cryptocurrency wallet or ask to receive it on the bank account.
Features
WeCashUp API enables you to securely collect or send money to your customers by different ways on web or mobile application in real time. The API support all currencies and process transactions with the best conversion rate.
Accept Payment
Request sample:
curl "https://www.wecashup.com/api/v2.0/merchants/pv2Ufd8hLFUeoG3rLJwYAethIcJ2/transactions"
-d "merchant_public_key=VDMPNb6RAfx9i9Qv4TZsmLPqQQ8EJUkV3Wnz3lTF2eo1"
-d "transaction_receiver_callback_url=https://www.wecashup.cloud/developers-v2/api-reference/callback/callback.php"
-d "transaction_method=pull"
-d "transaction_provider_mode=telecom"
-d "transaction_receiver_currency=XAF"
-d "transaction_receiver_total_amount=594426"
-d "transaction_receiver_reference=YND-BRZ001"
-d "transaction_sender_currency=XAF"
-d "transaction_conversion_rates_folder=2017-10-26T15"
-d "transaction_conversion_rate=1.0"
-d "transaction_sender_total_amount=594426"
-d "transaction_sender_splitted_amount=594426"
-d "transaction_sender_phone_number=00237671234567"
-d "[email protected]"
-d "transaction_sender_firstname=Musk"
-d "transaction_sender_lastname=John"
-d "transaction_sender_country_code_iso2=CM"
-d "transaction_sender_reference=YND-BRZ001"
-d "transaction_sender_lang=en"
-d "transaction_sender-shipping_country_code_iso2=CM"
-d "transaction_sender-shipping_town=Yaounde"
-d "transaction_sender-billing_country_code_iso2=CM"
-d "transaction_sender-billing_town=Yaounde"
-d "transaction_product_data=[{\"product_1\":{\"name\":\"BILLET-YND-BRZ\",\"quantity\":\"1\",\"unit_price\":\"594426\", \"category\":\"Billetterie\",\"reference\":\"XVT2VBF\",\"description\":\"Voyager en toute securite"}}]"
Response sample:
{
"response_details": "Created",
"response_content": {
"providers_list": [
{
"provider_order": 1,
"provider_instructions": "On your phone, compose #150*1*1*695636035*_AMOUNT_TO_PAY_*YOUR SECRET CODE# ",
"provider_communication_mode_asynchronous": true,
"provider_direct_ussd_capable": true,
"provider_telecom_transaction_init_mode": "ussd",
"provider_communication_mode_synchronous": true,
"provider_name": "Orange"
},
{
"provider_order": 0,
"provider_instructions": "On your phone, compose *126*1*1# and transfer _AMOUNT_TO_PAY_ _CURRENCY_ to the phone number : 653907288 ",
"provider_communication_mode_asynchronous": true,
"provider_direct_ussd_capable": false,
"provider_telecom_transaction_init_mode": "ussd",
"provider_communication_mode_synchronous": true,
"provider_name": "MTN"
}
],
"transaction_token": "4594e223a82dab393a02e1e21ef6bfac3f91110f",
"transaction_uid": "6329310055977767992",
"merchant_callback_url": "callback_url"
},
"response_errors": {},
"response_code": 201,
"response_status": "success"
}
WeCashUp API allows you as a merchant to accept Cash, Mobile Money, Credit Cards and Cryptocurrencies via a single API integration.
Accepting payment is the simplest way to use the API. When you create a transaction on type “payment” to collect money from your customer on your web or mobile application, you’re using the “Accept payment” feature, then you don’t need more actions for the transaction to be correctly processed.
Fore more details, go to the point create a transaction.
To accept a payment, you need to create a transaction of payment
type. Just as in the following request:
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/transactions
- Payload:
- merchant_public_key=
public_key
- transaction_receiver_callback_url=
callback_url
- transaction_type=
payment
- transaction_method=
pull
- transaction_provider_mode=
telecom
- transaction_receiver_currency=
XAF
- transaction_receiver_total_amount=
594426
- transaction_receiver_reference=
YND-BRZ001
- transaction_sender_currency=
XAF
- transaction_conversion_rates_folder=
2017-10-26T15
- transaction_conversion_rate=
1.0
- transaction_sender_total_amount=
594426
- transaction_sender_splitted_amount=
594426
- transaction_sender_phone_number=
00237671234567
- transaction_sender_email=
[email protected]
- transaction_sender_firstname=
Musk
- transaction_sender_lastname=
John
- transaction_sender_country_code_iso2=
CM
- transaction_sender_reference=
YND-BRZ001
- transaction_sender_lang=
en
- transaction_sender-shipping_country_code_iso2=
CM
- transaction_sender-shipping_town=
Yaounde
- transaction_sender-billing_country_code_iso2=
CM
- transaction_sender-billing_town=
Yaounde
- transaction_product_data:
- product_1:
- name=
BILLET-YND-BRZ
- quantity=
1
- unit-price=
594426
- reference=
YND-BRZ001
- category=
Billettreie
- description=
Voyager en toute sécurité
- name=
- product_1:
- merchant_public_key=
Split Payment
curl "https://www.wecashup.com/api/v2.0/merchants/pv2Ufd8hLFUeoG3rLJwYAethIcJ2/transactions"
-d "merchant_public_key=VDMPNb6RAfx9i9Qv4TZsmLPqQQ8EJUkV3Wnz3lTF2eo1"
-d "transaction_receiver_callback_url=https://www.wecashup.cloud/developers-v2/api-reference/callback/callback.php"
-d "transaction_method=pull"
-d "transaction_provider_mode=telecom"
-d "transaction_receiver_currency=XAF"
-d "transaction_receiver_total_amount=594426"
-d "transaction_receiver_reference=YND-BRZ001"
-d "transaction_sender_currency=XAF"
-d "transaction_conversion_rates_folder=2017-10-26T15"
-d "transaction_conversion_rate=1.0"
-d "transaction_sender_total_amount=594426"
-d "transaction_sender_splitted_amount=394426"
-d "transaction_sender_phone_number=00237671234567"
-d "[email protected]"
-d "transaction_sender_firstname=Musk"
-d "transaction_sender_lastname=John"
-d "transaction_sender_country_code_iso2=CM"
-d "transaction_sender_reference=YND-BRZ001"
-d "transaction_sender_lang=en"
-d "transaction_sender-shipping_country_code_iso2=CM"
-d "transaction_sender-shipping_town=Yaounde"
-d "transaction_sender-billing_country_code_iso2=CM"
-d "transaction_sender-billing_town=Yaounde"
-d "transaction_invites={\"user1\":{\"transaction_sender_email\":\"\",\"transaction_sender_phone_number\":\"00242066631234\",\"transaction_sender_preferred_method\":\"phone\",\"transaction_receiver_total_amount\":\"200000\",\"transaction_receiver_currency\":\"XAF\"}}"
-d "transaction_product_data=[{\"product_1\":{\"name\":\"BILLET-YND-BRZ\",\"quantity\":\"1\",\"unit_price\":\"594426\", \"category\":\"Billetterie\",\"reference\":\"XVT2VBF\",\"description\":\"Voyager en toute securite"}}]"
Split payment feature that enables merchants to allows customers to pay one transaction with different payment methods or to be help achieving the payment by invite their friends.
To create a split payment transaction, you need to create a transaction of payment
type. Then adding invited users parameters. Just as in the following request:
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/transactions
- Payload:
- merchant_public_key=
public_key
- transaction_receiver_callback_url=
callback_url
- transaction_type=
payment
- transaction_method=
pull
- transaction_provider_mode=
telecom
- transaction_receiver_currency=
XAF
- transaction_receiver_total_amount=
594426
- transaction_receiver_reference=
YND-BRZ001
- transaction_sender_currency=
XAF
- transaction_conversion_rates_folder=
2017-10-26T15
- transaction_conversion_rate=
1.0
- transaction_sender_total_amount=
594426
- transaction_sender_splitted_amount=
394426
- transaction_sender_phone_number=
00237671234567
- transaction_sender_email=
[email protected]
- transaction_sender_firstname=
Musk
- transaction_sender_lastname=
John
- transaction_sender_country_code_iso2=
CM
- transaction_sender_reference=
YND-BRZ001
- transaction_sender_lang=
en
- transaction_sender-shipping_country_code_iso2=
CM
- transaction_sender-shipping_town=
Yaounde
- transaction_sender-billing_country_code_iso2=
CM
- transaction_sender-billing_town=
Yaounde
- transaction_product_data:
- product_1:
- name=
BILLET-YND-BRZ
- quantity=
1
- unit-price=
594426
- reference=
YND-BRZ001
- category=
Billettreie
- description=
Voyager en toute sécurité
- name=
- product_1:
- transaction_invites:
- user1:
- transaction_sender_email
- transaction_sender_phone_number
- transaction_receiver_total_amount
- transaction_sender_preferred_method
- transaction_receiver_currency
- user1:
- merchant_public_key=
In this request, customer split the payment in two parts. He is going to paid 394426 XAF and then inviting a friend by phone number to complete the remain of 200000 XAF.
If the request succeed, the API will return the same response you receive when you accept a payment. Invitations are sent by email or SMS only when the invitor paid his or her own part of the transaction.
Note: Given it’s an additional payment feature, you must subscribe to enables split payment on your web or mobile application.
Push Payment
{
"response_details": "Created",
"response_content": {
"transaction": {
"transaction_method": "push",
"transaction_provider_mode": "mobile-money",
"transaction_sender_uid": "EvIvZFlBKNaMddjXJOOpEWNeWj52",
"transaction_sender_currency": "XAF",
"transaction_receiver_reference": "JOHN1990",
"date": "2018-03-23T11:38:53+0000",
"transaction_sender_total_amount": "594426.0",
"transaction_conversion_rate": "1.0",
"transaction_status": "PENDING",
"transaction_provider_name": "Orange",
"transaction_receiver_total_amount": "594426.0",
"transaction_uid": "6382913356389183607",
"transaction_receiver_country_code_iso2": "CM",
"transaction_receiver_currency": "XAF",
"transaction_receiver_uid": "6317033505725406952"
}
},
"response_errors": {},
"response_code": 200,
"response_status": "success"
}
This feature enables merchant to push money with any payment method to customers.
To create a Push payment transaction, you need to create a transaction with the following parameters:
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/transactions
- Payload:
- merchant_public_key=
public_key
- merchant_secret=
secret_key
- transaction_receiver_webhook_url=
webhook_url
- transaction_method=
push
- transaction_provider_mode=
mobile-money
- transaction_provider_name =
Orange
- transaction_receiver_reference=
YND-BRZ001
- transaction_receiver_total_amount=
594426
- transaction_receiver_currency=
XAF
- transaction_receiver_phone_number=
00237671234567
- transaction_receiver_email=
[email protected]
- transaction_receiver_firstname=
Musk
- transaction_receiver_lastname=
John
- transaction_receiver_country_code_iso2=
CM
- transaction_receiver_reference=
YND-BRZ001
- transaction_receiver_lang=
en
- transaction_receiver_shipping_country_code_iso2=
CM
- transaction_receiver_shipping_town=
Yaounde
- transaction_receiver_billing_country_code_iso2=
CM
- transaction_receiver_billing_town=
Yaounde
- transaction_product_data:
- product_1:
- name=
BILLET-YND-BRZ
- quantity=
1
- unit-price=
594426
- reference=
YND-BRZ001
- category=
Billettreie
- description=
Voyager en toute sécurité
- name=
- product_1:
- merchant_public_key=
If the request succeed, you will receive the response at right:
When the push is processing and money is push to customer account with success, you are going to be updated on your webhook url.
Airtime Top up
{
"response_details": "Created",
"response_content": {
"transaction": {
"transaction_method": "push",
"transaction_provider_mode": "airtime",
"transaction_sender_uid": "EvIvZFlBKNaMddjXJOOpEWNeWj52",
"transaction_sender_currency": "XAF",
"transaction_receiver_reference": "TOPUPN1425",
"date": "2018-03-23T11:38:53+0000",
"transaction_sender_total_amount": "594426.0",
"transaction_conversion_rate": "1.0",
"transaction_status": "PENDING",
"transaction_provider_name": "Orange",
"transaction_receiver_total_amount": "594426.0",
"transaction_uid": "6382913356389183614",
"transaction_receiver_country_code_iso2": "CM",
"transaction_receiver_currency": "XAF",
"transaction_receiver_uid": "6317033505725406952"
}
},
"response_errors": {},
"response_code": 200,
"response_status": "success"
}
Merchants can use this feature to top-up any prepaid mobile phone.
To create a Airtime top-up transaction, you need to create a transaction with the following parameters:
- Method :
POST
- Content-Type:
application/x-www-form-urlencoded
- Endpoint :
https://www.wecashup.com/api/v2.0/merchants/<MERCHANT_UID>/transactions
- Payload:
- merchant_public_key=
public_key
- merchant_secret=
secret_key
- transaction_receiver_webhook_url=
webhook_url
- transaction_method=
push
- transaction_provider_mode=
airtime
- transaction_provider_name =
Orange
- transaction_receiver_total_amount=
594426
- transaction_receiver_currency=
XAF
- transaction_receiver_phone_number=
00237671234567
- transaction_receiver_email=
[email protected]
- transaction_receiver_firstname=
Musk
- transaction_receiver_lastname=
John
- transaction_receiver_country_code_iso2=
CM
- transaction_receiver_reference=
TOPUPN1425
- transaction_receiver_lang=
en
- transaction_receiver_shipping_country_code_iso2=
CM
- transaction_receiver_shipping_town=
Yaounde
- transaction_receiver_billing_country_code_iso2=
CM
- transaction_receiver_billing_town=
Yaounde
- transaction_product_data:
- product_1:
- name=
TOPUPN1425
- quantity=
1
- unit-price=
50000
- reference=
TOPUPN1425
- category=
Credit
- description=
Recharge phone credit
- name=
- product_1:
- merchant_public_key=
Marketplace Mode
WeCashUp Marketplace allows you to split transactions from different sources and pay out your clients. You can define fees for each sub-merchants and we will send the appropriate funds to you and your sub-merchants. To onboard new sub-merchants, you need to collect information and send it to the API. The KYC is done in our side, so you don’t have to worry about it.
1. Onboarding Sub-merchant
Sub-merchants are individual sellers who provide services or goods under the WeCashUp Marketplace. As Merchant, you can onboard as many sub-merchant as you need on the API. You must collect some information regarding your sub-merchant, in order for us to process to the KYC and confirm the onboarding.
To create sub-merchant accounts, 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/<MERCHANT_UID>/submerchants
- merchant_public_key
- merchant_secret
- payload for each submerchant
- submerchant_1:
- merchant_email
- merchant_password
- merchant_country
- merchant_legal_name
- merchant_currency
- merchant_category (Individual or Company)
- submerchant_1:
If the request succeed, you receive a JSON object with sub-merchant details. When executing a transaction, payments are going to be sent directly in sub-merchant account after retrieving service fees you define.
Note: Given it’s an additional payment feature, you must subscribe to enables this mode on your web or mobile application.
2. Update Sub-Merchant
To update sub-merchant accounts, 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/<MERCHANT_UID>/submerchants/<SUB_MERCHANT_UID>
- merchant_public_key
- merchant_secret
- _method:
PATCH
- merchant_type:
SUBSELLER
- payload for each submerchant
- submerchant_1:
- merchant_country
- merchant_legal_name
- merchant_currency
- submerchant_1:
3. Service fees
Depending on the operating mode of your Marketplace, you must define service fees for transactions to be processed through your platform. You can define monthly fees for your sub-merchant when onboarding them, which means the same fees will be applied for each transaction of your sub-merchant. Or you can define it at every transaction from your sub-merchant. Transactions with no service fees will not be processed.
If you want to define the service fees when onboarding the sub-merchant, you must add transaction_service_fees
in the sub-merchant payload. This parameter must be greater than 0.0
and must be defined in percentage.
If you don’t define it when onboarding the sub-merchant, you must then send it when creating a transaction.
4. Create a transaction
When it comes to process transaction, you must be careful when creating transaction for your sub-merchants. You must correctly differentiate the flows from each sub-merchants.
To create a transaction for your marketplace merchants, you must create payment transaction with your credentials, then define the list of sub-merchant involved in the transaction and their part in the total amount.
If the request succeed, your are going to receive the same response as in the accept payment feature.
Escrows
In normal operation, When executing transactions in marketplace, sub-merchants funds are automatically release when customer pay the transactions. But, you can defer the payment of your sub-merchants by keeping their money in escrow account for a certain time (example: 7 days). After that time, funds are automatically going to be release to sub-merchant's account.
Plugins
If your application is hosted on a popular CMS, you can easily integrate the API by using one of our plugins.
- For Wordpress application with Woocommerce installed, you can find the WeCashUp pluging on the Wordpress Marketplace.
- For Prestashop application, you can finf the WeCashUp plugin on the Addons Marketplace
Our development team is working harder to create plugins for other CMS.