Overview

This documentation provides information about the REST API for Shopp!ng Pay. Shopp!ng Pay allows you as a developer to easily process payments using our intuitive endpoints.

All responses are in the following format:

{
  "status": "The response status. Will match the following regex: (success|error|fail)",
  "data": "The response data. Could be a JSON Object or Array. The specific datatype will be documented per endpoint",
  "message": "Optional message",
  "code": "Optional code used to identify the specific error when an error response is returned"
}

HTTP verbs

This RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

This RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

Resources

Merchant

A merchant is a subscriber of this service.

Complete your merchant registration

A POST request will complete your merchant registration.

Request structure

Path Type Description

business_name

String

The name of the business you want to integrate with this service

business_address

String

The address of the business you want to integrate with this service

phone_number

String

The contact phone number of the business you want to integrate with this service

bank_code

String

The bank code of the bank where payment from your customers should be deposited

account_number

String

The account number used for your business

contact_email

String

The contact email for your business

first_name

String

Your first name

last_name

String

Your last name

Response structure

Path Type Description

status

String

The response status

data

Object

The response data containing properties of the merchant account

message

String

The response message

Example request

$ curl 'https://api.shoppi.ng/payment/api/v1/merchants' -i -X POST -H 'Content-Type: application/json' -d '{
  "business_name" : "Zinobu enterprises",
  "business_address" : "Ikoyi",
  "phone_number" : "+23470000000",
  "bank_code" : "Stanbic",
  "account_number" : "1234567890",
  "contact_email" : "zainab@shoppi.ng",
  "first_name" : "Zainab",
  "last_name" : "Olapade"
}'

Example response

HTTP/1.1 201 Created
Location: https://api.shoppi.ng/payment/api/v1/merchants/43672ad42667f4908476cbd02566ee0d
Content-Type: application/json;charset=UTF-8
Content-Length: 180

{
  "status" : "success",
  "message" : "Registration was successful",
  "data" : {
    "location" : "https://api.shoppi.ng/payment/api/v1/merchants/43672ad42667f4908476cbd02566ee0d"
  }
}

Get information about the currently authenticated merchant

A GET request will return information about the currently authenticated merchant.

Request structure

Table 1. /api/v1/merchants/me
Parameter Description

Response structure

Path Type Description

status

String

The response status

data

Object

The response data containing properties of the merchant account

Example request

$ curl 'https://api.shoppi.ng/payment/api/v1/merchants/me' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 492

{
  "status" : "success",
  "data" : {
    "client_id" : "custom_client_id",
    "merchant_id" : "3b3c461e88a303d25400e0ca13eafb70",
    "business_name" : "Zinobu enterprises",
    "business_address" : "Ikoyi",
    "phone_number" : "+23470000000",
    "bank_code" : "Stanbic",
    "account_number" : "1234567890",
    "is_live" : false,
    "contact_email" : "zainab@shoppi.ng",
    "first_name" : "Zainab",
    "last_name" : "Olapade",
    "secret" : "a11c31d64b949de9de4afa3ac6afed94"
  }
}

Payment

Payment is the act of depositing funds into a merchant’s account.

Initiate a payment operation

A POST request will initiate a payment operation.

Payment can be initiated using either of two modes:

  1. Browser-to-server mode: This mode doesn’t require authentication/authorization. You will be required to send the MAC (i.e. Message Authentication Code) of the input fields. The MAC is computed by first constructing an encoded message by delimiting the input parameters with the | character in the following format: order_id|redirect_url|narration|merchant_id|cust_phone|cust_full_name|cust_email|amount|back_url MAC Computation in Java

    import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    import org.apache.commons.codec.binary.Base64;
    public class ApiSecurityExample {
      public static void main(String[] args) {
        try {
         String secret = "secret"; // Available at GET /api/v1/merchants/me
         String message = "Message"; // The encoded message constructed above.
         Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
         SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
         sha256_HMAC.init(secret_key);
         String hash = Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes()));
         System.out.println(hash);
        }
        catch (Exception e){
         System.out.println("Error");
        }
       }
    }
  2. Server-to-server mode: This requires authentication/authorization. The mac and merchant_id fields can be ignored from request body.

Request structure

Path Type Description

amount

Number

The amount to deposit

redirect_url

String

The URL where payment feedback should be sent

back_url

String

The URL of the site the customer came from

merchant_id

String

The merchant id of the merchant whose account the customer is paying to

narration

String

Brief description of the transaction being made

order_id

String

The ID used to identify this order on the merchant site

cust_full_name

String

The customer’s full name

cust_phone

String

The customer’s phone number

cust_email

String

The customer’s email address

mac

String

The Message Authentication Code

Response structure

Path Type Description

status

String

The response status

data.token

String

The token to be used for finalizing the payment

message

String

The response message

Example request

$ curl 'https://api.shoppi.ng/payment/api/v1/pay/initiate' -i -X POST -H 'Content-Type: application/json' -d '{
  "amount" : 10000,
  "redirect_url" : "http://yesmall.ng/paymentResponse",
  "back_url" : "http://back_url.com",
  "merchant_id" : "c2627ac10b68d6de87916284d14b3788",
  "narration" : "Bought a pair of shoes on Yesmall",
  "order_id" : "yesmall_shoe_234",
  "cust_full_name" : "Taiwo Adegoke",
  "cust_phone" : "+2348030000000",
  "cust_email" : "customer@email.com",
  "mac" : "UrwYQp5NLN3pEaZNapNb5ZKlRF+VuyCno5gg7iO7Azg="
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 132

{
  "status" : "success",
  "message" : "Transaction initiated",
  "data" : {
    "token" : "f60e1950fefca4d19a76fac2b5a42775"
  }
}

Finalize a payment operation

A POST request will finalize a payment operation.

Request structure

Path Type Description

card_number

String

The customer’s card number

card_cvv

String

The customer’s card cvv

card_pin

String

The customer’s card pin

expiry_month

String

The expiry month of the customer’s card

expiry_year

String

The expiry year of the customer’s card

Response structure

Path Type Description

status

String

The response status

message

String

The response message

data.payment_ref

String

The payment reference

Example request

$ curl 'https://api.shoppi.ng/payment/api/v1/pay/finalize/f60e1950fefca4d19a76fac2b5a42775' -i -X POST -H 'Content-Type: application/json' -d '{
  "card_number" : "5637 3465 1102 3811",
  "card_cvv" : "793",
  "card_pin" : "1111",
  "expiry_month" : "05",
  "expiry_year" : "19"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 138

{
  "status" : "success",
  "message" : "Transaction completed",
  "data" : {
    "payment_ref" : "097db47966eef2d606386fed962c31ea"
  }
}