API Documentation

Increased trust on your ecommerce store, app, classifieds or marketplace

Escrow Kenya’s highly simplified API installs “Buy With Escrow” buttons on your product listings or checkout pages. This way buyers can take advantage of the security of escrow payments without ever leaving your website or app, while sellers can close so much more sales when trust issues are eliminated.

How it works

• The e-commerce platform integrates Escrow Kenya API on its product or checkout pages.
• When a buyer clicks the “Buy With Escrow” button, an order is created at Escrow Kenya and the buyer is taken to the escrow payment interface.
• Seller and product details are fetched automatically by the API. The buyer then provides additional information about their agreement with the seller where applicable.
• The buyer then secures their order by logging on or registering and completing payment on the escrow payment interface.
• Upon successful payment, the buyer is redirected to the ecommerce platform.

Provided no issues arise between the buyer and seller, money is automatically released to the seller on a specified date or when the buyer approves the release of funds, whichever comes sooner.

Getting Started

Before you begin:

• Logon to the Partners Portal. If you do not have an account, create one here.
  
  

  Note: The email address you use to register on the Partner's Portal should match the email address used on the profile that publishes products on your website. This way, orders placed on your website will be matched to your merchant account at Escrow Kenya. If you'd rather use a different email address, a new merchant account will be created on Escrow Kenya, the first time an order is placed on your website.



• Under API Access/Integrations click Add App


• Upload a high-quality logo of your website/company. This may be used in the branding of our email communications with you, merchants and buyers on your platform, and will be displayed on the payment interface.


• Fill out your:
  • Preferred API Username e.g. WebsiteName
  
  
  • A description of your platform e.g. "Marketplace dealing in assorted goods from different suppliers."
  
  
  • Brand URL, e.g. www.websitename.com
  
  
  • Platform Type:
    • E-Commerce Store: You are the sole merchant on your website, selling products/services to various buyers.
    
    
    • Marketplace: Your website offers a platform for other merchants to list their products for sale.
    
    
  • (optional) Select the Service Category: Electronics, General Goods, General Services, Motor Vehicles or Freelancing Accounts.
    Note: Please leave this field blank if your platform will have both general goods and motor vehicles listed for sale.
  
  
  • (optional) Select Fee Payment option, i.e., who pays escrow fees in any transaction on your platform: Buyer, Seller, Shared (Buyer & Seller).
    Note: If left blank, the buyer will have the option to choose between sharing the fees with the seller or bearing the fee in full.

For Marketplaces: You will see an extra option to declare if your marketplace collects a commission from the sales. If it does, indicate the percentage commission. Your commission will be escrowed in every order and availed for each successful order. You will receive email notifications about all orders.

Once submitted, an API Key will be created and a request to activate it raised with us. You can proceed with integration right away but the integration will not work until the API key is activated. This is typically done within 30 minutes during business hours.

You will receive an email confirmation once the API key is activated and the status will change from “Pending Approval” to “Active”. Should your request be declined, you will receive an email notification advising you on what you should do to resolve the issue. The status will change to “Attention Required” and you will have an option to make amendments and submit them for review.

Skip to WordPress Woocommerce installation

Required Data

The API needs to fetch the following data.

• Your redirect URL: Where do you want to send the user if they cancel or complete checkout?
• Unique item- or order ID
• Item title or description
• Item cost (selling price)
• Currency
• Seller's email address
• Seller's phone number

Installation: Custom Websites

The API key and username will be used to create an access token that you will send with every request to Escrow Kenya. To create the access token, concatenate the username and API key with a full stop (.) in between, then encode the string using base64 encoding scheme. The access token and other required data is to be sent as a JSON object. The payload details are as shown below. Because JSON data structure can be generated from any language, we have provided only one illustration using PHP.

Basic Integration Sample (PHP)

<?php
 //prepare data to send
 $dataObj = new stdClass();
 $dataObj->ek_access_token = base64_encode("{username}.{apikey}");
 $dataObj->ek_access_type = "api_access";
 $dataObj->ek_redirect_url = "{YOUR_REDIRECT_URL}";
 $dataObj->ek_item_unique_identifier = "{UNIQUE_ITEM_OR_ORDER_ID}";
 $dataObj->ek_item_title = "{ITEM_TITLE_OR_DESCRIPTION}";
 $dataObj->ek_seller_email = "{SELLER_EMAIL}";
 $dataObj->ek_seller_phone = "{SELLER_PHONE}";
 $dataObj->ek_item_cost = "{ITEM_COST}";
 $dataObj->ek_item_currency = "{CURRENCY}";

/* EXTRA FIELDS WHERE YOU WANT TO SKIP LOGIN/REGISTRATION STEP */
$dataObj->ek_item_due_date = "{DUE_DATE_FOR_ORDER}";
$dataObj->ek_item_fee_paid_by = "{FEES_PAID_BY}"; /* optional; might be part of integration app */
$dataObj->ek_item_shipping_fee = "{SHIPPING_FEE}"; /* optional */
$dataObj->ek_buyer_name = "{BUYER_NAME}";
$dataObj->ek_buyer_phone = "{BUYER_PHONE}";
$dataObj->ek_buyer_email = "{BUYER_EMAIL}"; /* optional */
$encodedData = urlencode(json_encode($dataObj));
?>

<form action="https://escrowkenya.com/api/v1/orders/start_view" method="POST">
   <input type="hidden" name="payload" value="<?php echo $encodedData; ?>">
   <button type="submit" class="escrow">Buy with Escrow Kenya</button>
</form>
                        

WordPress/WooCommerce