Introduction

Co-op connect offers a safe and simple way to try out the available Co-operative bank APIs. This API is a sandbox version; its purpose is to make developers a chance to safely experiment, test and build applications on top of our available APIs before they are ready to go to production.

The documentation gives an overview of all the APIs which are available and the structure and depth of these APIs.

This API implementation is Representational State Transfer Service (RESTful service in short).

The responses produced by the Co-op APIs are in JavaScript Object Notation, JSON format.


Getting started

Sign Up

Click on the 'Sign Up' link at the top right hand of the page to access the registration page. Fill in the form wit hthe required details and submit the form. Fill in your username and password.


You will receive a popup message confirming your registration.


Click 'OK' to be redirected to the login page.

Enter the username and password that you had supplied during registration and click Sign In. You will be redirected to the home page as shown:

Congratulations! You are now a member of the platform.


Create test application

In the API management world, an application is a logical way of grouping related APIs. This enables developers to reuse existing access keys (consumer key, secret key) and tokens for making related calls. For instance, a developer can decide to use same keys for all B2B requests.

On the left panel, you can see a list of menus. Click on Applications to access the list of available applications in which case you can choose to use the default ones or create your own.

Subscribe to API(s)

  1. Once you are logged in, you will be presented to the following page:
  2. Select the application from the dropdown list. Application is a way of grouping related APIs.
    You can equally create your own application using steps described earlier.
  3. Click “Subscribe”. A popup message appears as shown:

Generate Access Tokens

  1. Click on “Applications” on the left panel.
  2. Chooses the application for which you want to generate tokens
  3. Say you created an application called TestApp. Click on the TestAPP link. You will be directed to a page that looks as shown below:
  4. Choose the appropriate environment from the tabs(production or sandbox ). In this manual, we have chosen Sandbox.
  5. Specify callback URL and then click “Generate keys”. Leave other fields have default values;
  6. The token generated is available for use in the console and even in SOAP UI. Note that you can generate the tokens externally using curl or any suitable tool as shown

Authenticate

A user is already authenticated once they login.


Test our APIs

After generating a token , you will proceed to test the APIs using the following steps:
  1. Choose the API that you want to test by clicking on the APIs link on the left menu.
  2. Choose API Console from tabs that appear in the middle of the page.
  3. Expand the API link to get the API parameters as defined by swagger.
  4. Click “Try out” to test the API. You will be given separate test parameters for each API

Internal Funds Transfer

The funds transfer API allows you to make a single transfer funds request from your Co-operative Bank account to any other Co-operative Bank account. The transaction allows a single debit and a single credit in KES.

Authentication

An Access Token will be used to access, authorize and authenticate your interactions with the Co-op Bank’s Open Banking APIs. It will be generated using a Consumer Key and a Consumer Secret linked to your account. The Access Token will expire after a specified duration of time, after which regeneration of the Access Token will be required. To generate or re-generate an Access Token, your sign-in username and password will be required. It is very important to keep your API credentials safe, as they can be used to access your account, make changes to your account and carry out transactions. It is also important to note that once you generate a new set of API credentials you must update all your applications with the new API details for your applications to continue working. Note that the Sandbox and Live environments have unique Consumer Key and Consumer Secret which are NOT be interchangeable.

How to initiate a Funds Transfer Request

Developers will make a HTTP POST Request to an API Endpoint with the appropriate API Parameters for a specific API call. A JSON acknowledgement Response containing a status code and status description will be returned immediately from the platform. Our Open Banking APIs will enable developers to initiate the following transaction requests:
  1. Fund Transfer
  2. Transaction Status Enquiry
You can initiate the funds transfer request by sending a HTTP POST request to:

https://developer.co-opbank.co.ke/fundstransfer

The following headers will be required for each request:
Header Description
AuthenticationToken
  • String
  • Required
  • This is your auth key from the platform
    Field Description
    Debit account
  • Integer (14)
  • Required
  • This in the account number from where the payment will be initiated
    Debit account BranchCode
  • Integer (8)
  • Required
  • This is the source bank account branch code where the account number is registered
    Credit account
  • Integer (14)
  • Required
  • This is the account number to which you want to send a payment
    Credit account BranchCode
  • Integer (8)
  • Required
  • This is the destination bank account branch code where the account number is registered
    Narration
  • String (min1, max 15)
  • Required
  • A short description of the transaction that can be displayed on the customer statement
    TransactionCurrency
  • String
  • Required
  • This is the defined currency for the transaction, ISOCurrencyCode e.g. KES
    TransactionAmount
  • Decimal
  • Required
  • This is the amount you want to send
    Reference
  • String (min1 max15)
  • Required
  • This is your unique transaction identifier

    What does the API respond with?

    These are the fields for an acknowledgement response from Co-op Bank Open Banking to API Consumer for funds transfer request.
    Field Description
    MessageReference
  • String (min 1, max 15)
  • This is your unique transaction identifier as passed in the request
    MessageDateTime
  • DateTime
  • This is the time when the transaction request was received
    e.g. 2018-06-08T12:06:06
    MessageCode
  • String
  • The acknowledgment message return code [0, -1, -2, -3, 900901]
    MessageDescription
  • String
  • This is the description of the MessageCode received
    e.g. “CONNECTION ERROR”

    Funds Transfer Request : Request Body JSON Schema

    { "MessageReference": "", "CallBackUrl": "", "Source": { "Narration": "", "BranchCode": "", "TransactionCurrency": "", "AccountNumber": "" }, "Destination": { "Narration": "", "BranchCode": "", "TransactionCurrency": "", "AccountNumber": "" }, "TransactionAmount": "" }


    Sample RESTful Funds Transfer Request

    { "MessageReference": "ABCD1234", "CallBackUrl": "https://localhost:8250/ConsumerService/v1.0.0/test", "Source": { "Narration": "Electricity payment", "BranchCode": "00011002", "TransactionCurrency": "KES", "AccountNumber": "01234567890123" }, "Destination": { "Narration": "Electricity payment", "BranchCode": "00011002", "TransactionCurrency": "KES", "AccountNumber": "54321987654321" }, "TransactionAmount": "123456.78" }


    Synchronous JSON Acknowledgement Response: Response Body JSON Schema

    { "MessageReference": "", "MessageDateTime": "", "MessageCode": "", "MessageDescription": "" }


    Sample JSON Acknowledgement Response

    { "MessageReference": "ABCD1234", "MessageDateTime": "2018-06-08T16:06:02", "MessageCode": "900900", "MessageDescription": "CONNECTION ERROR" }


    API Responses and Response Codes

    HTTP Status Code Error Code Error Message Description Examples
    200 0 REQUEST ACCEPTED SUCCESSFULLY This is the success acknowledgement response from Co-op Bank Open Banking to API consumer where the funds transfer request is accepted. Success Acknowledgement Response
    409 -1 DUPLICATE MESSAGE REFERENCE This is the duplicate transaction acknowledgement response from Co-op Bank Open Banking to API consumer where the API consumer used an already existing message reference on the funds transfer request. Duplicate Transaction Acknowledgement Response
    401 -2 AUTHORIZATION FAILURE This is the debit account authorization failure acknowledgement response from Co-op Bank Open Banking to API consumer where the API consumer does not operate the debit account on the funds transfer request Debit Account Authorization Failure Acknowledgement response
    400 -3 THE AMOUNT DEBITED OR CREDITED MUST BE GREATER THAT 0 This is error acknowledgement response where the API Consumer initiated a transaction request with zero (0) or negative transaction amount. Zero (0) or negative transaction amount.
    408 -4 REQUEST TIMED OUT This is the error response sent from Co-op Bank Open Banking to API consumer when the backend, SOA, would be unavailable. Backend Unavailable
    503 700700 API blocked This API has been blocked temporarily. Please try again later or contact the system administrators. Invoke an API which is in the BLOCKED lifecycle state
    429 900800 Message throttled out The maximum number of requests that can be made to the API within a designated time period is reached and the API is throttled for the user. Invoke an API exceeding the tier limit
    503 900801 Hard limit exceeded Hard throttle limit reached Invoke an API exceeding the hard throttle limit
    500 900900 Unclassified authentication failure An unspecified error has occurred Backend service for key validation is not accessible when trying to invoke an API
    401 900901 Invalid credentials Invalid authentication information provided Using an older access token after an access token has been renewed.
    401 900902 Missing credentials No authentication information provided Accessing an API without the Authorization: Bearer header
    401 900905 Incorrect access token type is provided The access token type used is not supported when invoking the API. The supported access token types are application and user accesses tokens. See Access Tokens. Invoke API with application token, where the resource only allows application user tokens
    403 900906 No matching resource found in the API for the given request A resource with the name in the request can not be found in the API. Invoke an API resource that is not available
    401 900907 The requested API is temporarily blocked Happens when the API user is blocked. Invoke API resource with a subscription that has been blocked by the API publisher
    403 900908 Resource forbidden The user invoking the API has not been granted access to the required resource. Invoke an unsubscribed API
    401 900909 The subscription to the API is inactive The status of the API has changed to an inaccessible/unavailable state. Invoke an API resource with a subscription that has not yet been approved by the administrator.
    403 900910 The access token does not allow you to access the requested resource Can not access the required resource with the provided access token. Check the valid resources that can be accessed with this token. Invoke API resource with an access token that is not generated to be used with the resource's scope.
    400 102511 Incomplete payload The payload sent with the request is too large and the client is unable to keep the connection alive until the payload is completely transferred to the API Gateway Sending a large PDF file with the POST request

    Callback

    This is the callback request from Co-op Bank Open Banking to API Consumer’s callback URL with the funds transfer processing results. It is an asynchronous JSON request The Callback will be sent with the following fields
    Field Description
    TransactionID
  • String
  • Co-operative Bank's processed transaction number
    MessageDateTime
  • DateTime
  • DateTime of the message
    ResponseCode
  • String
  • The code identifying the current status of the request
    ResponseDescription
  • String
  • A text description of the current status of the request
    Message Reference
  • String (min 1, max 15)
  • Your unique transaction Identifier
    Narration
  • String (min 1, max 25)
  • Source account transaction narration
    Branch code
  • Integer (8)
  • Source bank account branch code
    TransactionCurrency
  • String
  • Source bank account currency. ISOCurrency code
    AccountNumber
  • Integer (min 1, max 14)
  • Source bank account number to be debited
    Narration
  • String (min 1, max 25)
  • Destination account transaction narration
    Branch code
  • Integer (8)
  • Destination bank account branch code
    TransactionCurrency
  • String
  • Destination bank account currency. ISOCurrency code
    AccountNumber
  • Integer (min 1, max 14)
  • Destination bank account number to be debited
    Amount
  • Decimal
  • Amount to be credited into the destination account

    Callback: Response Body JSON Schema

    { "TransactionID": "", "MessageDateTime": "", "ResponseCode": "", "ResponseDescription": "", "MessageReference": "", "Source": { "Narration": "", "BranchCode": "", "TransactionCurrency": "", "AccountNumber": "" }, "Destination": { "Narration": "", "BranchCode": "", "TransactionCurrency": "", "AccountNumber": "" }, "TransactionAmount": "" }


    Sample Callback Request

    { "TransactionID": "123456789123456789", "MessageDateTime": "2018-06-11T09:22:49", "ResponseCode": "0", "ResponseDescription": "Request Processed Successfully", "MessageReference": "ABCD1234", "Source": { "Narration": "Fee payment", "BranchCode": "00011002", "TransactionCurrency": "KES", "AccountNumber": "12345678912345" }, "Destination": { "Narration": "Fee payment", "BranchCode": "00011002", "TransactionCurrency": "KES", "AccountNumber": "54321987654321" }, "TransactionAmount": "123456.78" }


    JSON Callback Request Response Codes Description

    Response Code Error Message
    40421536 Unable to process the transaction now, please initiate it again.
    40409528 Account is Dormant
    40007323 No debits. Referral required overriding.
    40243028 Value Date is before Account Open Date for the account
    40000132 Account is Closed
    40000304 From Date greater than To Date
    40407606 Transaction Reference Not Found
    40108300 Cannot Process Transaction. Please check Product Transaction eligibility for Account
    40112172 Account is stopped
    40007325 No credits. Referral required overriding.
    40205109 Supervisor Authorization Required
    40007322 No debits allowed.
    40422049 Transaction already posted
    40180194 No debit allowed on the account
    20020000 Account does not exist
    20201005 Please fund the settlement account and process from retry queue
    40000127 An unexpected error occurred - Reinitiate Transaction
    40007319 Referral required for posting.
    40112171 Referral required for posting and enquiry.
    40411056 Customer is Not Active
    40000126 Account cannot be found
    40007321 Account stopped. No Posting or Enquiry is Allowed
    40507020 Insufficient Available Balance
    40180193 No credit allowed on the account

    Transaction Status Enquiry

    This is RESTful Transaction Status Enquiry Request interface called by an API consumer to APIM to enquire the status of an earlier requested transaction.
    Below is the Fund Transfer API Resource URL: https://developer.co-opbank.co.ke/TransferStatus/
    The response message from Co-op Bank Open Banking to API Consumer for Transaction Status Enquiry Request is the same message as Callback Request with the funds transfer processing results
    The response is synchronous
    The required fields for the request:
    Header Description
    BearerToken:
  • String
  • Required
  • Provide Bearer Token for Authorization using Basic Authentication.
    Field Description
    Reference:
  • String (min 1, max 15)
  • Required
  • This is your unique transaction identifier
    Callback URL
  • String
  • Required
  • Your callback URL that will receive results after processing your transaction
    E.g. https://yourdomain.com/ftresponse

    Request Body JSON Schema

    { "MessageReference": "", "CallBackUrl": "" }


    Synchronous JSON Transaction Status Enquiry Response – Co-op Bank Open Banking to API Consumer

    The response message from Co-op Bank Open Banking to API Consumer for Transaction Status Enquiry Request is the same message as Callback Request with the funds transfer processing results


    Test Cases

    As a developer, the test cases will be available to you for download as you are creating the sandbox app.

    The test cases are in place to ensure that you have well understood the API structure for requests and responses for our different APIs. These test cases are in an excel spreadsheet that you should fill in with the results from each of the test scenarios that you want to consume.

    As the Test cases will cover all the APIs available, you will only be required to carry out the test cases for the APIs you had initially selected.


    Go - Live

    Once you have already tried out the APIs on our platform and have tested these against our test cases provided, you can make a formal request to go to production.

    You will need to have the test cases duly filled, then send an e-mail request, together with these filled in test cases, to our support team who will guide you on the next steps to enable you to get to production.

    Send the e-mail request and the test cases to E-ChannelsandE-commerce@co-opbank.co.ke