OGO Pay Documentation

What is OGO Pay?

OGO Pay is a payment gateway platform that enables you to accept credit and debit card payments in your web and mobile applications.

VISA, MasterCard, and Union Pay cards are currently supported.
Tokenization is supported.
This gives you the ability to store your customers’ payment methods. Thereby facilitating business models that involve non-interactive payment flows used in subscriptions and introducing convenience in online stores and other e-commerce businesses
Only cards supporting 3DSecure can be used.
3DSecure is an additional layer of authentication provided by card issuers to validate the cardholder. The customer will be directed to their bank’s webpage to validate a transaction via an OTP. We use this method to validate a card before tokenising it.
Installment plans are supported.
This allows your customer to split a large payment into equal monthly instalments.
Pre Auth + Completion model is supported.
Preauthorization allows you to verify funds in a customer’s card and then complete the transaction at a later time. This enables business models that do not charge for the product or service on the same day, such as hotel reservations and car rentals.
Automated daily settlements.
All successful sales transactions will be settled in your bank account the next banking day.

Currently, all merchants must have a bank account with Commercial Bank to receive funds. Other banks will be supported soon.

How to become a Merchant?

Send us an email at contact@pay.ogo.today with your details.
We will send you test credentials to start integrating into our test environment.
In the meantime, we will discuss rates, agreements, and other financial matters with the bank.
Once your integration into the test environment is complete, let us know. We will run through a few scenarios to confirm everything is in good order.
By this time, you would have your agreements and rates confirmed and your bank account created and ready.
Once the test integration is satisfactory and bank accounts are ready, we will provide you with live credentials to go live.

Note If you have any questions during integration, please mail us at support@pay.ogo.today

Getting Started

There are two ways of capturing card data. The easiest way is to load and display our card capture webpage. The other is to build your customised card capture form and submit the details to us via an API endpoint.

Load and display our card capture page in your application.
Next, implement a response handler in your application backend.
Finally, integrate a call to perform a purchase transaction from your application backend.

Using Our Card Capture Page

Build the hosted page URL in the following format and display it in a mobile app web-view, iframe, etc.

				
					https://{{baseUrl}}/defaulthostedpage?returnUrl={{responseHandler}}&merchantId={{yourMerchantId}}&customerId={{yourCustomersId}}

Replace the following

baseUrl with the live or test baseUrl ()
returnUrl should be your response handler endpoint
merchantId should be the live or test environment merchantId provided to you
customerId should be the unique customerId on your end, which you will later use when performing transactions.

Response Handler

An endpoint has to be implemented in your application backend that will process a POST request with data submitted as a form (application/x-www-form-urlencoded).

The following fields will be submitted to your endpoint.

success (true or false)
message (Card tokenised successfully or an error message)
token (card token if successful)
cardMask (masked card number in the format 4242-42xx-xxxx-4242)
expiryMonth (two-digit month)
expiryYear (two-digit year)
cardType (V for Visa, M for Mastercard and U for Unionpay)
merchantId (the merchant id sent with the tokenise API call)
customerId (the customer id sent with the tokenise API call)
orderId (the order id sent with the tokenise API call)

It is your responsibility to process the incoming data and save the token with the relevant customer. You will be using this token in all future transactions related to this card. Once you complete processing the response, you have to redirect to a different page in your website, or in the case of a mobile app, redirect to a URL that can be caught by a listener in your webview and process accordingly.

Purchase Transaction

Send a Purchase Transaction whenever you wish to perform a transaction using a customer’s tokenized card. Initiate this transaction from your application backend. Make every effort to avoid double submissions. Refer to Authentication to calculate and include a hash in your request. You are expected to save the responses from this API call whether successful or not. This data is important during troubleshooting.

API Reference

Base URLs

Test Environment – https://test-ipg.ogo.exchange

Live Environment – https://live-ipg.ogo.exchange

Please contact us to obtain credentials.

Authentication

All transaction-related endpoints require an Authorization Header and a Date Header to be set in the HTTP request. These headers should be in the following format.

				
					Authorization: OGO <merchantid>:<hmac-hash>
Date: <ISO-DATE-TIME>

For Example:

				
					Authorization: OGO kangaroo:C7WInYIVNkjhFUD5MWtjqJkLX5qU+vJLDfFYSUiMSog=
Date: 2019-02-27T12:27:53.331Z

To calculate the hash, create a string that consists the current Date in ISO-DateTime format on the first line and the body of the request on the second line. Lines should be separated with the new line character (‘\n’). This string should then be used with the provided merchant secret key to create an HmacSHA256 hash. The hash should then be converted to Base64 encoding. The final Base64 encoded hash, should be included in the Authorization Header.

JavaScript

PHP

Example

JavaScript

When the secret key is "AXz7ovfpCdzznQMgFUnN8IPlyH1+qAVMjF5CaYbopIc=" And the date is "2019-06-02T09:30:01.561Z"

For the following request string... {"amount":100,"token":"3173b35fcc744fa88c5cdb425838cd08","orderId":"an-order-id","customerId":"23"}

The string to sign will be... (date and request string separated by newline) 2019-06-02T09:30:01.561Z

{"amount":100,"token":"3173b35fcc744fa88c5cdb425838cd08","orderId":"an-order-id","customerId":"23"}

The resulting hmac hash will be... NI5HlmdhylurFACRLFuqbzWVokAldAu8lXUFzLzfsH0=

PHP

<?php
// the secret key provided for the merchantid
$secret = "5azaobIk7jvdFsRvuO11Ko3WkAoKEpMAz4JMvOrxkbs=";

$isoDateTime = date('c');
$jsonString = json_decode($body);
$strToSign = $isoDateTime."\n".$jsonString;
$hmac = hash_hmac('sha256', $strToSign, $secret, true);
$hash = base64_encode($hmac);

Example

When the secret key is "AXz7ovfpCdzznQMgFUnN8IPlyH1+qAVMjF5CaYbopIc="
And the date is "2019-06-02T09:30:01.561Z"
For the following request string...
{"amount":100,"token":"3173b35fcc744fa88c5cdb425838cd08","orderId":"an-order-id","customerId":"23"}

The string to sign will be... (date and request string separated by newline)
2019-06-02T09:30:01.561Z
{"amount":100,"token":"3173b35fcc744fa88c5cdb425838cd08","orderId":"an-order-id","customerId":"23"}

The resulting hmac hash will be...
NI5HlmdhylurFACRLFuqbzWVokAldAu8lXUFzLzfsH0=

Operations

Get API Version

Returns the API Version

Request

				
					GET /version

Response

				
					{
  "name": "OGO Pay",
  "version": "2.0.0"
}

Tokenize Card – HTML

Initiates card tokenization process.
Returns an HTML response that can be used to redirect the user or show in an iframe.
This request should be sent from the user’s browser as an HTML form submission.

Request

				
					POST /registercard-html
Content-Type: application/x-www-form-urlencoded

Body

				
					cardHolderName=Mr%20Customer&
cardNumber=4242424242424242&
expiryMonth=12&
expiryYear=21&
merchantId=your-merchant-id&
customerId=your-customer-id&
orderId=an-order-id&
returnUrl=https%3A%2F%2Fbackend.myapp.com%2Fcard-tokenize-response-handler

Response

A succesfull response will have status code 200 and an html page in the content. A failure response will either have a 400 or 500 status code and an error message in the content.

Tokenize Card – JSON

Initiates card tokenization process.
Returns an HTML result that must be shown in a webview.
This request should be sent from the mobile app.

Request

				
					POST /registercard-json
Content-Type: application/json

Body

				
					{
  "cardHolderName": "Mr Customer",
  "cardNumber": 4242424242424242,
  "expiryMonth": 12,
  "expiryYear": 19,
  "merchantId": "your-merchant-id",
  "customerId": "your-customer-id",
  "orderId": "an-order-id",
  "returnUrl": "https://backend.myapp.com/card-tokenize-response-handler"
}

Response

				
					{
  "success": true,
  "message": "3DSecure Page",
  "result": "<!DOCTYPE HTML PUBLIC..."
}

Purchase Transaction

These requests must be sent by the backend service. An HMAC-SHA256 hash needs to be calculated using the merchant secret key. The HTTP Authorization header must contain this hash. Refer to Authentication on how to calculate the hash.

Request

				
					POST /purchase
Authorization: OGO merchantid:hmac-hash

Body

				
					{
  "amount": 20050,
  "token": "1d75cb9494bd437ab2bbc6ed7e5c9933",
  "orderId": "100DCEFGH",
  "customerId":"123"
}

Response

				
					{
  "success": true,
  "message": "Transaction successfull",
  "result": {
    "referenceNumber": "228680501735",
    "responseCode": "00",
    "approvalCode": "3jcPVy",
    "date": "03/13",
    "time": "13:14:21",
    "invoiceNumber": "976593",
    "stan": 922515,
    "type": 200,
    "transactionId": "3b2d9f5c-d8d3-4220-a1f8-13babe066050",
    "message": "Approved"
  }
}

Invalid Token error If you get an "Invalid Token" error, make sure you are sending the same customerId used with the token when registering the card.