Transactions

---

 

 

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

Enabling customers to create orders in a seamless way 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":"5549397032"
    }

Name	Type	Description
merchant_id	Number	Id gotten during merchant creation
country_code	Number	Refer to the country_code table
amount	Number	Amount to be initiated
msisdn	Number	Customers number
desc	String	Description of the order
reference	Number	A unique id for verification

 

Where the merchant_id is the id given during setup while the Country Code can be found in the Country Code table

 

Example

 

Expected 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"
        }
    }

 

#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.

Name	Type	Description
merchant_id	Number	Acquired during registration
country_code	String	Refer to the Country code table
amount	Number	The amount gotten from invoice
msidn	Number	Customer's number
desc	String	Description
reference	String	Reference from the invoice

 

   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"
        }
    }

Example Case :

 

 

#Initiate a payment

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

Reference  the first table

Name	Type	Description
merchant_id	Number	Id gotten during merchant creation
country_code	Number	Refer to the country_code table
amount	Number	Initiate order amount
msisdn	Number	Customers number
desc	String	description of the order
reference	Number	Reference recieived from the initiated order
payment_gateway_code	Number	The access code generated from the payment gateway code request
child_merchant_Id	Number	This is the id of your sub merchant

   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"
    }

Example :

Expected 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": ""
    }
}

Note, this payment will be completed online by the customer but for the test, it can be simulated locally

POST '{{base-url}}/payment/simulation'

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

Meanwhile if the selected gateway as a service downtime or can not be reached, this had been handled for you

Example case :

 

#Create an Invoice

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

Name	Type	Description
merchant_id	Number	The id is given during merchant creation
amount	Number	Expected amount from the recipient
msisdn	Number	recipients phone number
reference	Number	a unique reference for the created invoice

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

Payload :

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

Expected Response :

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

Example

The referece must be unique else you run into a reference error

 

#Get Bank List

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 update on the bank list or drop your request on the comment section.

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

Reference  the first table

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"
            },
          .
          .
          .
          ]
    } 

Example :

 

#Get A List Of Available Payment gateways

This encompases 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'

Reference  the first table

Response :

        {
            "status": "success",
            "data": [
                {
                    "gateway_code": 93,
                    "gateway_name": "Bank Transfer",
                    "gateway_description": " to pay with Bank Transfer (Preferred by most users)"
                },
                {
                    "gateway_code": 113,
                    "gateway_name": "Bank Transfer",
                    "gateway_description": " to pay with Bank Transfer (Preferred by most users)"
                },
                .
                .
                .
            ]
        }

Example :

 

 

#Confirm Payment Status

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

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

Name	Type	Description
merchant_id	Number	Id gave during Merchant creation
order_reference	Number	The generated id for the payment
contry_code	Number	refer to the country_table

 

Response :

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

 Example Case:

if the payment is yet to be successful, it returns Awaiting Payment

Example Case :

 

Else, if you send a wrong order id in your request, it returns an Invalid Order_Id

Example Case: