Overview

Introduction

The Ogaranya API is a service that provides RESTful APIs for creating, initiating, and accepting payments via SMS. The API responds with JSON payloads in most cases, unless stated otherwise. When sending data to the API, parameters should be passed as valid JSON, and the request should include the header "Content-Type: application/JSON" to indicate the data format being sent.

Environment

We have two environments:

Staging: this can be used to test your integration. No accurate checks are performed when in the Staging environment.

Production: To provide you with access to the production environment, we require that the integration is tested first. We just want to make sure that everything works the way it should.

This is the staging environment and its access can be regulated with the use of an authorization header. During your onboarding, you will be provided with the production endpoint

Authentication

API users are expected to pass the token and public_key through their request header for authorization.

Making a request

All requests must contain the following headers:

API Health

On API Health, you can easily understand the health status of the API and its returned Status Codes.

To check the operational status of our service, you can use the following request. If the response you receive includes an HTTP status code of 200, it confirms the availability of your API.

   curl -X GET \
     'https://api.staging.ogaranya.com'



    

Success Response:

#Errors

The response body contains a JSON payload with additional information. Click here to see more Errors

For example:

{
  "status": "Error",
  "message": "You don't come to a party without your Token and Public key",
}

Country Codes

Creating a Sub-merchant

Registered merchants can create sub-merchants under them.To create a new sub-merchant, Make a call to the endpoint below with the payload in the stated format.

   curl -X POST \
     '{{base-url}}/{country_code}/merchant'

Payload :

{
    "name": "Olubusayo store",
    "phone": "2348068869429",
    "email": "a@b.com",
    "address": "17 lekki road, langbasa rd, Ikeja",
    "contact_person": "Olubodun",
    "charge_commission_to_merchant": "0",
    "manage_stock": "0",
    "use_custom_payment": "1",
    "payment_gateway_group_id": "1",
    "“Show_name_on_payment_gateway”": 1,
    "“custom_flow_settings”": {
      "skip": [
        "customer_name",
        "shipping_address"
      ]
    },
    "payment_gateway_settings": {
      "MerchantId": "4057",
      "Username": "ogavalue","Password": "dfdfd"
    },
    "account_details": {
      "bank_code": "058",
      "account_number": "1213323232",
      "account_name": "Okenwa Akinyele"
    }
  }

Expected Response :

{
        "status": "success",
        "data": {
            "message": "Merchant successfully created."
        }
    }

API Token

#Retrieve Merchant's API token

This endpoint retrieves the merchant API token

   curl -X GET \
     '{{base-url}}/{merchant_id}/api/token/'

Expected response :

{
        "status": "success",
        "data": {
            "token": "2349160006677",
            "private_key": "9QxaJ&?WMsr5k3UwB$XGEQj3C$g*%6*eqsyXR%Hn2YR*h&?S6ZQJurjHSXX?d*wmTYgz%@"
        }
    }

Transactions

This is a set of endpoints or methods provided by Ogaranya, that developers can use to perform various text-based payment-related operations.

#Create an order to be completed by the customer through sms

Enabling customers to create orders seamlessly is a way to improve customer satisfaction. To do this, a request should be sent with a header to the following endpoint

   curl -X POST \
     '{{base-url}}/{merchant_id}/pay/{country_code}'

Payload :

{
      "amount": "500",
      "msisdn": "2348068869417",
      "desc": "Testing",
      "reference":"8864905934"
    }

The merchant_id is the id given during setup while the country_code can be found in the Country Code table.

Response :

{
        "status": "success",
        "data": {
            "order_id": "8864905934",
            "order_reference": "8864905934",
            "message": "To complete this transaction, Text ORDER 5549397032 to 08011223344",
            "msisdn_to_send_to": "08011223344"
        }
    }

#Initiate a payment to be completed online

Payment can be initiated by choosing the preferred gateway and including its code in the request.

   curl -X POST \
     '{{base-url}}/{merchant_id}/pay/{country_code}/{payment_gateway_code}'

Payload :

{
      "amount": "500",
      "msisdn":"2348068869417",
      "desc": "Testing",
      "reference":"ssssssdddde",
      "child_merchant_id":"2348068869429"
    }

Response :

{
    "status": "success",
    "data": {
        "message": "Your order ID is 5549397032. Total amount is ₦500.00. Pay by transfer into the account below. \n\n Bank: FSDH Merchant Bank \n Account Number:  \n Account Name: Neolife.\n\nNB: THIS ACCOUNT DETAILS IS VALID ONLY FOR THIS TRANSACTION AND IT WILL EXPIRE IN 1hr.\n",
        "order_reference": "5549397032",
        "dialing_code": ""
    }
}

#Create an Invoice

This is to create an invoice to be sent to the customers' phones.

   curl -X POST \
     ' {{base-url}}/{merchant_id}/invoice'

Payload :

{
      "amount": "500",
      "msisdn": "2348068869417",
      "reference":"12536373893"
    }

Respose :

        {
            "status": "success",
            "data": {
                "msisdn": "2348159174839",
                "order_id": "2247371120",
                "reference": "222393",
                "total": 500,
                "message": "2348159174839 -> ₦500.00, Ref: 2247371120"
            }
        }

#Request for payment gateway codes

For payer to get the available payment gateway options available for them to pay, You should send a POST request to this endpoint with the appropriate payload and Header.

   curl -X POST \
     ' {{base-url}}/{merchant_id}/payment/gateway/{country_code}'

Payload :

    {
        "amount": 500,
        "msisdn": "2348159174839",
        "desc": "Test",
        "reference": "4358346267"
    }

Response :

    {
        "status": "success",
        "data": {
            "message": "To pay, reply with:\n\n12  for GTBank\n13  for Zenith Bank\n21  to pay with Remita RRR"
        }
    }

#Get Bank List for Settlement

This returns the list of banks available for settlement. Banks not in the list are yet to be integrated into our system, you can always check back for updates on the bank list or drop your request in the comment section.

   curl -X GET \
     '{{base-url}}/{merchant_id}/banks'

Response :

{
        "status": "success",
        "data": [
            {
                "bank_code": "044",
                "bank_name": "ACCESS BANK PLC",
                "bank_sort_code": "044150149"
            },
            {
                "bank_code": "014",
                "bank_name": "MAINSTREET BANK PLC",
                "bank_sort_code": "014150030"
            },
          .
          .
          .
          ]
    } 

#Get A List of Available Payment gateways

This encompasses available payment gateway options and their code. Please note that availability and suitability of these payment gateways may vary depending on your country and specific business requirements

   curl -X GET \
     '{{base-url}}/{merchant_id}/payment/gateway'

Response :

{
    "status": "success",
    "data": [
        {
            "gateway_code": 93,
            "gateway_name": "Bank Transfer",
            "gateway_description": " to pay with Bank Transfer (Preferred by most users)"
        },
        {
            "gateway_code": 95,
            "gateway_name": "GTbank",
            "gateway_description": " for GTBank USSD"
        },
        {
            "gateway_code": 97,
            "gateway_name": "UBA",
            "gateway_description": " for UBA USSD"
        },
        .
        .
        .
    ]
}

#Confirm Payment Status

Confirmation of payment can be easily done by checking its status through the endpoint below

   curl -X GET \
     ' {{base-url}}/{ merchant_id }/payment/{order_reference}/status/{country_code}'

Response :

{
        "status": "success",
        "data": {
            "message": "Payment successful",
            "status": "SUCCESSFUL",
            "meta": []
        }
    }

Wallet

Wallet in this context, is a virtual store where money is saved for a transactional purpose. This is so swift as it doesn't have to go through the bank to complete the transaction. It is one of the numerous features our system offers. In a case where gateways are down, this will be a messiah.

#User wallet

User wallet is to enhance customer satisfaction. Note that this is a transactional wallet and can only be debited by an authorized merchant.

#Create a user Wallet

This endpoint serves as a gateway for users to initiate the wallet setup process. Creating a wallet is a crucial step that enables access to diversify transactions within our system.

   curl -X POST \
     '{{base-url}}}/2348068869417/wallet'

Payload :

 {
    "firstname": "Olubodun",
    "surname": "Akinyele",
    "phone": "2348068869417",
    "gender": "male",
    "dob": "5/9/1999",
    "bvn": "22224827394"
 }

Response :

    {
         "code": "200"
        "status": "",
        "data": {
            "message": ""
        }
    }

#Debit a user Wallet

This endpoint enables authorized merchant to charge a user wallet.

   curl -X POST \
     '{{base-url}}/2348068869417/wallet/debit'

Payload :

 {
    "phone": "2348068869345",
    "account_number": "11000233295",
    "amount": "100",
    "payment_gateway_code": "122"
}

Response :

    {
        "status": "success",
        "data": {
            "order_id": 5124823934;
            "payment_reference": "0W-40WE77903T7917g67qD6UHW83y2u4idmb7d73w792J"
        }

    }

#Generate random BVN

This endpoint provides you with random BVN which you can use in our test environment. This can be run in your browser. All you need to do is to click here or copy the endpoint to your browser, then click on the generate button. Yes, your BVN is ready.

   curl -X GET \
     'https://topinfo.ng/bvn-generator/'

#Get a wallet Infomation

Send a request to this endpoint to retrieve informations about an active wallet.

   curl -X GET \
     '{{base-url}}/transactional/wallet/'

#Get a wallet Histoty

To fetch an history of a wallet transaction.

   curl -X GET \
     '{{base-url}}/transactional/wallet/'

#Top up a wallet

You can easily move money to your wallet by sending a command to us. text TOP AMOUNT to 08107600076 through any of the acceptable sales channels.

#Merchant wallet

Merchants are provided with a transactional wallet which they can top up, check balance, and also use in completing transactions for their customers.

#To complete an order through merchant wallet.

In a case where a merchant wallet is to be charged for a completed order, you should call on this endpoint with the required information.

   curl -X GET \
     '{{base-url}}/transactional/wallet/{{ gateway_code }}/{{ order_id }}'

#Get merchant wallet balance

Send a get request to get the available wallet balance.

   curl -X GET \
     '{{base-url}}/transactional/wallet/'

Simulation

An imitation of a live model in a controlled environment. This gives room for the emulator to study the flow, pattern of response and behavioral pattern of the live model

#Message simulation

The message simulation feature allows developers to test and emulate the behavior of messages within our system. It provides a convenient way to observe how messages flow, interact, and respond in a simulated environment.

   curl -X GET \
     '{{base-url}}/bot/simulation/{ message }'

Example:

#Payment simulation

Payment is to be completed online by the customer but it can be simulated with the following endpoint.

   curl -X POST \
     ' {{base-url}}/payment/simulation'

Payload :

{
         "order_reference": "5467870645",
         "amount": 600
     }

Example:

Products

Our API provides you with a variety of product types -

#Create a Product

   curl -X POST \
     '{{base-url}}/{merchant_id}/products'

payload

    {
      "name": "test",
      "qty": "1",
      "price": "23232",
      "desc": "tetsting",
      "type": "product",
      "case_quantity":
      "23",
      "case_price": "12",
      "weight" : "223"
    }

Response :

    {
        "status": "success",
        "data": {
            "code": "285429"
        }
    }

#Edit a Product

Products can be edited and updated by calling on the following endpoint

   curl -X PUT \
     '{{base-url}}/{merchant_id}/product/code/{product_code}'

Payload :

    {
        "name": "test",
        "qty": "1",
        "price": "23232",
        "desc": "tetsting",
        "type": "product",
        "case_quantity":
        "23",
        "case_price": "12",
        "weight" : "2293"
    }

Response :

    {
        "status": "success",
        "data": {
            "message": "Product successfully updated"
        }
    }

#Delete a product

Products can be deleted by passing it code to the query in a DELETE request.

   curl -X DELETE \
     '{{base-url}}/{merchant_id}/product/code/{product_code}'

Response :

    {
        "status": "success",
        "data": {
            "message": "Product successfully deleted"
        }
    }

#Get all created products by type

To fetch the list of all available products, query this endpoint.

   curl -X DELETE \
     '{{base-url}}/{merchant_id}/products/{product_type}'

Expected response :

    {
        "status": "success",
        "data": [
            {
                "code": "059288",
                "name": "test",
                "price": 23232,
                "desc": "testing",
                "type": "product",
                "case_quantity": 23,
                "case_price": 12,
                "weight": "product",
                "created": "2023-06-26 14:54:29",
                "updated": "2023-06-26 14:54:29"
            },
            .
            .
            .
        ]
    }

#Get product by product_code

A single product can be fetched with its product_code

   curl -X GET \
     '{{base-url}}/{merchant_id}/product/code/{product_code}'

Expected Response :

    {
        "status": "success",
        "data": {
            "code": "059288",
            "name": "test",
            "price": 23232,
            "desc": "testing",
            "type": "product",
            "case_quantity": 23,
            "case_price": 12,
            "weight": "223",
            "created": "2023-06-26 14:54:29",
            "updated": "2023-06-26 14:54:29"
        }
    }