JavScript Module

Introduction

This module can be used as a service inside JS environments like ReactNative applications This service requires two dependencies:

Axios: handles sending requests to the API
SHA256: handles signature generation

You can download the service file from here, or copy and paste the following code in service.js file

import axios from 'axios';
import SHA256 from 'sha256';

axios.defaults.baseURL = 'https://cowpay.me/api/v1/'; // or: https://staging.cowpay.me/api/v1/

export default class CowpayService {

    constructor(merchantCode, merchantHash, token) {
        this.merchant_code = merchantCode;
        this.merchant_hash = merchantHash;
        this.token = token;
    }

    creditCardChargeRequest(params) {
        return axios.post('charge/card', {
            merchant_reference_id: params.merchant_reference_id,
            payment_method: params.payment_method,
            customer_merchant_profile_id: params.customer_merchant_profile_id,
            card_number: params.card_number,
            expiry_year: params.expiry_year,
            expiry_month: params.expiry_month,
            cvv: params.cvv,
            customer_name: params.customer_name,
            customer_mobile: params.customer_mobile,
            customer_email: params.customer_email,
            amount: params.amount,
            description: params.description,
            signature: SHA256([
                this.merchant_code,
                params.merchant_reference_id,
                params.customer_merchant_profile_id,
                params.amount,
                this.merchant_hash
            ].join('')),
            
        }, {
            headers: {
                'Content-Type': 'application/json',
                'Accept': 'application/json',
                'Authorization': `Bearer ${this.token}`
            }
        })
    }

    fawryChargeRequest(params) {
        return axios.post('charge/fawry',
            {
                merchant_reference_id: params.merchant_reference_id,
                customer_merchant_profile_id: params.customer_merchant_profile_id,
                customer_name: params.customer_name,
                customer_mobile: params.customer_mobile,
                customer_email: params.customer_email,
                amount: params.amount,
                signature: SHA256([
                    this.merchant_code,
                    params.merchant_reference_id,
                    params.customer_merchant_profile_id,
                    params.amount,
                    this.merchant_hash
                ].join('')),
            }, {
                headers: {
                    'Content-Type': 'application/json',
                    'Accept': 'application/json',
                    'Authorization': `Bearer ${this.token}`
                }
            })
    }

    getPaymentStatus(merchant_reference_id) {
        return axios.get('charge/status', {
            params: {
                merchant_reference_id: merchant_reference_id,
                signature: SHA256(this.merchant_code + merchant_reference_id + this.merchant_hash)
            },
            headers: {
                'Accept': 'application/json',
                'Authorization': `Bearer ${this.token}`
            }
        })
    }
}

Instructions

Instantiating the service

To use the service methods you need to create an instance with three constructor parameters: merchantCode, merchantHash and authorization token which you can get from API settings page in your cowpay portal

import Service from './service';

let CowpayService = new Service('GHKjd452155z', 'hash key', 'authorization token')

Card Charge Requests

Function creditCardChargeRequest is used to charge customers using their credit cards, this function takes one object parameter holds the required data for charge request, and the parameters description as follows:

service.creditCardChargeRequest({
    customer_merchant_profile_id: 253,
    customer_name: 'John Doe',
    customer_email: 'example@gmail.com',
    customer_mobile: '+201xxxxxxxxx',
    merchant_reference_id: 1121,
    card_number: 5123456789012346,
    cvv: '123',
    expiry_month: 05,
    expiry_year: 21,
    amount: '10.00',
    description: 'Testing card charge request'
})
    .then(response => {
        console.log(response)
    })
    .catch(error => {
        console.log(error.response)
    })

Responses

// success
{
    success: true,
    status_code: 200,
    status_description: 'Operation done successfully',
    type: 'Credit Card Charge Request',
    cowpay_reference_id: 40652,
    merchant_reference_id: 11,
    payment_gateway_reference_id: '96548574965'
}

// invalid data with 422 status code
{
    success: false,
    status_code: 422,
    status_description: "The given data was invalid.",
    errors: {
        merchant_code: "Invalid merchant code"
    }
}

// failed to process payment charge request
{
  success: false,
  status_code: 4040,
  status_description: " Payment attempt failed. Please try again later  "
}

3d-secured cards

If the used credit card has any 3d-secure measures enabled the payment won't be processed directly but instead the payment operation will require the OTP confirmation, and you can handle this step using the OTP plugin by following the mentioned instructions here

Pay at Fawry

Function fawryChargeRequest is used to issue fawry payment code to be used for payment at the nearest fawry outlet, it also takes one object parameter holds the payment data and the parameters are described as follows:

service.fawryChargeRequest({
    customer_merchant_profile_id: 253,
    customer_name: 'Testing',
    customer_email: 'example@gmail.com',
    customer_mobile: '+201xxxxxxxxx',
    merchant_reference_id: 1121,
    amount: '10.00',
    description: 'Testing fawry charge request'
})
    .then(response => {
        console.log(response)
    })
    .catch(error => {
        console.log(error.response)
    })

Response

// success
{
    success: true,
    status_code: 200,
    status_description: 'Operation done successfully',
    type: 'Charge Request',
    cowpay_reference_id: 40689,
    merchant_reference_id: "1122",
    payment_gateway_reference_id: "96566210475" // is the code to use for payment
  }

Check Payment Status

Function getPaymentStatus is used to get charge request updated status and it takes one parameter: merchant_reference_id

service.getPaymentStatus(1121)
    .then(response => {
        console.log(response)
    })
    .catch(error => {
        console.log(error.response)
    })

Responses

// success
{
    success: true,
    status_code: 200,
    status_description: "Operation done successfully",
    type: "Get Payment Status",
    merchant_reference_id: "1121",
    cowpay_reference_id: 40653,
    order_status: "PAID"
}

// invalid data
{
    success: false,
    message: "The given data was invalid.",
    status_code: 422,
    status_description: "The given data was invalid.",
    errors: {
        merchant_reference_id: "The selected merchant reference id is invalid."
    },
    type: "Get Payment Status"
}

// Not found
{
    success: false,
    status_code: 404,
    status_description: "Not found",
}