Cofred Automated Payments Interface (API) Guide

Cofred Automated Payments Interface (API) Guide For use by Cofred Merchants. This guide describes how to connect to the Automated Payments Interface (API) www.cofred.com Version 1.0

Copyright 2015. Cofred. All rights reserved. The material contained in this guide is copyrighted and owned by Cofred together with any other intellectual property in such material. Except for personal and non-commercial use, no part of this guide may be copied, republished, performed in public, broadcast, uploaded, transmitted, distributed, modified or dealt with in any manner at all, without the prior written permission of Cofred, and, then, only in such a way that the source and intellectual property rights are acknowledged. To the maximum extent permitted by law, Cofred shall not be liable to any person or organisation, in any manner whatsoever from the use, construction or interpretation of, or the reliance upon, all or any of the information or materials contained in this guide. The information in these materials is subject to change without notice and Cofred. Assumes no responsibility for any errors. Version Control Table Date Version Description 25/08/2015 1.1 Cofred Checkout Payment 25/08/2015 1.1 Cofred Onsite Payment

Content Table 1. About This Guide 4 1.1 Objectives and target audience. 4 1.2 Related documentation 4 2. Introduction. 5 2.1 Connecting to the Wallet Checkout 6 2.2 Steps in the payment process 7 2.2.1 Redirecting customers to the Cofred Gateway (Step 1). 7 2.2.1.1 Recommended secure method of redirecting the customer. 9 2.2.2 Cofred Customer Login/Registration (Step 2).. 10 2.3 Pay by MTN Mobile money.. 11 2.4 Example code for Checkout Processing. 12 2.5 Cofred Onsite payment. 13 2.5.1 Using the Cofred Onsite payment 13 2.5.1.1 For Generating Invoice. 13 2.5.1.2 For Checking Invoice status.. 13 2.5.1.3 For Cancelling the status. 14 2.5.2 Response codes & their meaning in Onsite Processing. 14 3. Merchant Account setup 15 4. Security.. 16 4.1 SECURITY.... 16 4.2 SECURITY RESTRICTION. 16

1. ABOUT THIS GUIDE 1.1 Objectives and Target Audience This guide provides details on how to connect your website to the Cofred Wallet Checkout using the Cofred Wallet service. It is intended for users who have a working knowledge of HTML. The guide covers the steps in the payment process and the information that needs to be passed from your web servers to Cofred, to enable Cofred to process payments. This guide is only relevant to Cofred Wallet merchants. 1.2 Related documentation You should use this guide together with the additional Cofred Wallet Checkout and Cofred onsite processing documents described below. Guide Automated Payments Interface Guide Description Describes how to connect to Cofred using the Automated Payments Interface (API). This supports functionality such as merchant queries against the system, receiving money. 1.3 Conventions used in this guide The table below lists some of the conventions used in this guide. Table 1: List of conventions Convention Reference File path Glossary Description Indicates a reference to another section in this guide. For example, refer to the Introduction on page 5. Used to indicate a file path or folder structure. Glossary term

2. INTRODUCTION 1) The Cofred Wallet Checkout is a secure Cofred site, where you redirect customers from your website to make a Wallet payment through Cofred. The gateway collects customer payment details using standard HTML forms. After the payment is complete, the customer is returned to your website and you receive a realtime notification of the payment, which includes details of the transaction. 2) The Cofred Onsite processing provides the facility to make payment on your website using an HTML form. It will not need any redirection to our site like Checkout process. After the successful payment you can redirect user on your specified url. Requesting a Sandbox account You may need a Sandbox account to test your integration to the Cofred Wallet Checkout. Sandbox accounts work only in a Test environment. You need to change your API settings in Merchant Tools option in your Merchant account, also you need to pass the test url. Funds cannot be sent from a Sandbox account to a live account but it will show to your Sandbox account. To set up a Sandbox account: 1. To create a sandbox account it needs to access merchant account where merchant will need to click on top right (Down arrow). 2. Merchant will see a Create Sandbox Account link in a box.

3. After clicking on the link it will open the form to setup a sandbox account. All fields in the form will be pre-filled. Merchant will just need to enter his pin to proceed. 4. After submitting the request a screen will show with all the login details of sandbox account. Merchant will also get the email with all the details. 5. After successful creation of sandbox account 10,000 will be credited in account to test the api. Who to contact for queries For all support queries, contact the Merchant Services department: Email: merchantservices@cofred.com

2.1 Connecting to the Wallet Checkout Connecting to the Cofred Wallet Checkout requires adding Cofred as a payment method on your website s checkout or payment page. When your customer selects Cofred, you should ensure that they are redirected to the Cofred Wallet Checkout. At the same time you will need to submit information about the payment, such as your merchant account email, amount to be paid and several other hidden text fields. You can use a standard HTML form to collect and pass payment and customer details to Cofred. A simplified illustration of the transaction flow is shown in Figure 1 below. Figure 1 Cofred transaction flow 1. When the customer is ready to pay for goods or services on your website, they select the Cofred payment option on your website. 2. You request a session identifier (SID) by passing customer and transaction details (e.g., amount, Transaction id) to the Cofred Wallet Checkout. 3. Cofred returns the generated SID. 4. Using the payment button you redirect the customer to the Cofred Wallet Checkout which includes the session identifier in the redirect URL. Cofred displays the relevant payment page. 5. The customer enters their payment information, like Cofred account number and Password. 6. If customer Account number & Password is valid, after that Customer need to enter their account pin. 7. The system will check the balance of user either they have sufficient amount to make the transaction or not. 8. After successful transaction customer will be redirected to the page which merchant website (Which merchant provided in the api setting) with Status PAID. 9. After transaction cancelled customer will be redirected to the page which merchant website (Which merchant provided in the api setting) with Status NOT PAID.

2.2 Steps in the payment process Cofred Automated Payments Interface (API) Guide 1.0 Payment details are collected from the customer and you are notified of the result. The customer is then automatically returned to the relevant page on your website: 1 2 3 4 5 Redirect Customer login Choose Payment Cofred Return to customer to Method and Pay Transaction Merchant Cofred Payment status page website Page 2.2.1 Redirecting customers to the Cofred Gateway (Step 1) When a customer is on the online checkout or payment page on your website, they should be presented with a Pay by Cofred button (see example below). You can download a copy of this button in different sizes from the Cofred website at: https://www.cofred.com/brand-centre When they select the Cofred button, your website should post the HTML form containing their transaction details to https://cofredgh.com/secure/live/process_payment (For Live) or https://cofredgh.com/secure/demo/process_payment (For Test). The HTML form should contain the hidden input fields as shown in the api demo. Note: To maximise conversion, Cofred recommends that you redirect customers to the Cofred Wallet Checkout in the same browser window or embed the Cofred page in an iframe (see section 3.9 on page 35). When using the standard Cofred page, the minimum width of the window or frame should be at least 600 pixels. Cofred Wallet Checkout demonstration If you want a demonstration of the Cofred Wallet Checkout you can access a test form at: https://cofredgh.com/secure/demo Note: transactions are processed as real payments unless you use a demo account and demo cards. Contact the Merchant Services department merchantservices@cofred.com for a demo account. Download payment method logos Cofred logos and payment method icons that can be displayed on your website are available at: http://www.cofred.com/brand-centre Note: You will need your Cofred Account Number to use this section of Cofred.com Cofred 2015 8

Parameters to be posted to the Cofred Gateway Table 2: Cofred Wallet Checkout parameters Cofred Automated Payments Interface (API) Guide 1.0 Field name Description Required Max length Merchant Details Merchant Order ID Example value Transaction/Order ID from merchant website Yes 50 111110000 Amount Amount which merchant needs to deduct. Yes 20.00 Api Key Merchant will get this key from Cofred merchant tool configuration. Yes 13 8517403439152 Api Name Merchant will get this Name from Cofred merchant tool configuration. Yes merchant api return_url This parameter needs to be setup on merchant account in merchant tools options. Yes http://cofredshop.com/sto re//home/check_status For Live - https://cofredgh.com/secure /live/process_payment api_url This is where Merchant will post all data. It will be different for both Live & Demo Mode. Yes For Demo https://cofredgh.com/secure /demo/process_payment 2.2.1.1 Recommended secure method of redirecting the customer This method can be used to ensure that details of the payment are communicated securely between your server and Cofred. Important! We strongly recommend that you use this method for redirecting your customers to Cofred, as it does not require sending any payment parameters to their browser. This prevents customers from being able to view or modify any hidden parameters in your source code. Cofred 2015 9

How to implement Cofred Automated Payments Interface (API) Guide 1.0 To ensure that details of the payment are communicated securely only between your server and Cofred: 1. Your web server makes a standard POST request with the payment parameters, using the prepare_only parameter (see Table 2 above). 2. The Cofred server prepares a session for the payment and returns a standard HTTP(S) response. 3. After that it will show a payment form where customer will need to enter his Cofred account number & Password. 4. After successful Login user will prompt for the Cofred Pin. 5. After Pin verification customer will be redirected to the Merchant website with success response which includes Transaction ID, Payment Status, Payment Date, Amount Paid etc. 2.2.2 Cofred Customer Login/Registration (Step 2) When the customer submits the HTML form from their web browser they are shown a Cofred page that displays the payment amount and payment details submitted to Cofred and presents two options: login, or sign up. The two options are described in detail below. Step 1 Login Screen This screen will contain fields to enter Account number and Password. Also, contain the payment details & Order ID. Step 2 Screen after successful Login This screen will show the balance of Customer Account & Enter the account pin. After Balance & Pin confirmation Customer will be redirected to the success screen. Cofred 2015 10

Cofred Automated Payments Interface (API) Guide 1.0 Step 3- Screen after Payment Success This screen shows the payment success. After that customer will be redirected to the merchant website with success response. 2.2.3.1 Pay by MTN Mobile money This option allows customers to pay using Mtn Mobile money. Step 1 Here user will insert his Mtn Account details and submit the form. Cofred 2015 11

Cofred Automated Payments Interface (API) Guide 1.0 Step 2 After making a request Mtn will send message to complete the transaction of the related MTN customer. After successful payment user will be redirected to the success page. Cofred 2015 12

3.4 Cofred Onsite payments Cofred Automated Payments Interface (API) Guide 1.0 Cofred offers an Onsite payment service which enables you to make customer pay being on your website without redirecting to Cofred. For this you need to configure a popup (Also provided in the api demo) where you need to show account number field in the first step and need to call url to create invoice. Steps:- 1) First you need to show account number field here customer will enter their account number. 2) After that system will check & verify account number. 3) If entered account number is correct the Customer will get One-Time Password (OTP). 4) Customer will need to enter the received OTP in the second screen which he/she will get in the second screen (In case of multiple OTP customer will need to enter last OTP they get). 5) After successful OTP verification Merchant can set up the redirection according to their need. For Generating Invoice:- $merchant_api='8517403439152'; $merchant_account='0017170280'; $user_account=$_post['account_number']; $amount=$_post['amount']; $order_id=$_post['merchant_order_id']; $json_url = "https://cofredgh.com/secure/live/onsite/create_invoice?merchant_api=".$merchant_api."&merch ant_account=".$merchant_account."&customer_account=".$user_account."&amount=".$amount." &merchant_order_id=".$order_id; Merchant need to pass the same parameters in the url to create the invoice. For Checking Invoice status:- $invoiceno=$_post['invoiceno']; $pin=$_post['pin']; $json_url = "https://cofredgh.com/secure/live/onsite/invoice_status?invoiceno=".$invoiceno."&pin=".$pin; $json_data = file_get_contents($json_url); In second step merchant need to pass the invoice number & Pin(Entered by Customer). For Cancelling the status :- $invoiceno=$_post['invoiceno']; $json_url = "https://cofredgh.com/secure/live/onsite/invoice_cancel?invoiceno=".$invoiceno; $json_data = file_get_contents($json_url); To cancel the invoice merchant need to pass the invoice number in the url. Cofred 2015 13

Response codes & their meaning in Onsite Processing:- Cofred Automated Payments Interface (API) Guide 1.0 Code Message 000 Success code for all kind of successful activity(create Invoice, Paid Invoice, Cancel Invoice) 100 For merchant api configuration (Invalid Merchant details!) 101 If merchant is not verified by admin yet. 102 If api setting is in live mode & you are testing it in Demo mode or respectively. 103 If customer account is not valid. 104 If account number is registered only as a client. 105 Amount related error a) In demo mode it will show error if amount field is empty. b) In live mode it will show error if amount field is empty or payee account balance is low than the payment balance. 106 After creating invoice if developer will not send the generated invoice number properly in the second step then this error will show. 107 If invoice already used or it passes the maximum required time this error will show stating as Invoice Expired! Note:- Currently maximum time limit is 30 minutes. 108 If inserted pin is invalid this error will show. Cofred 2015 14

3. Merchant Account setup Cofred Automated Payments Interface (API) Guide 1.0 To set up a merchant account and enable it to receive payment you need to fill the form below(in Merchant Tools option) after that you will get api key which you need put it in the api configuration. Cofred 2015 15

4. SECURITY Cofred Automated Payments Interface (API) Guide 1.0 4.1 SECURITY All requests to the API must be standard HTTPs requests. The HTTPs protocol provides a secure means of verification of the program on the client host. Plain text HTTP requests are forbidden and if the client sends an HTTP request to the server it will be denied. TIP: If you currently do not send HTTPs headers for tracking reasons, you should be aware that this can be used as a loophole by potential web site hackers. Cofred 2015 16