NAV Navbar
html cURL PHP
  • Introduction
  • Authentification
  • Errors
  • Pagination
  • Versioning
  • Integration
  • MAIN RESOURCES
  • Merchants
  • Customers
  • Transactions
  • Products
  • Conversion rates
  • Webhooks
  • Payment Channels
  • Features
  • Plugins

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

    1. Create.
    2. Read.
    3. Update.
    4. 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:

    1. Sign up to get API keys.
    2. Setup the checkout page with credentials (HTML form or plugin setting page of the CMS).
    3. 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).

    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

    1. 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.

    2. 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.

    3. 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”).

    4. 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.

    5. 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.

    6. 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).

    7. 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.

    8. 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.)

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

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

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

    12. 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)

    13. 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.

    14. 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.

    15. 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 :

    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 :

    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 :

    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 :

    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 :

    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 :

    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 :

    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 :

    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:

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

    Retreive a transaction

    To get details about a transaction, you must send a request to the API endpoint with the following parameters :

    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.

    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 :

    Retrieve a product

    To get details about a product, you must send a request to the API endpoint with the following parameters :

    Update a product

    To update a product, you must send a request to the API endpoint with the following parameters :

    Delete a product

    To delete a product, you must send a request to the API endpoint with the following parameters :

    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 :

    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:

    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:

    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:

    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:

    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:

    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 :

    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 :

    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.

    Our development team is working harder to create plugins for other CMS.

    html cURL PHP