Iframe

How it works

Iframe payment methods enables merchants to process card payments without processing the card data on merchant server as teh card data sent from customer browser to cowpay directly

Initiate the payment token

Send a POST request to initiate an order token used for processing card data later

Request Endpoints

https://cowpay.me/api/v1/iframe/token
https://staging.cowpay.me/api/v1/iframe/token

Make sure to send all the listed below headers and keys with the proper values

Headers

HeaderValue
AuthorizationBearer Token
Content-Typeapplication/json
Acceptapplication/json

Keys

FieldRequiredTypeDescription
merchant_reference_idyesstringUnique alphanumeric value required as identifier for the charge request
customer_merchant_profile_idyesstringAlphanumeric ID of the customer being charged on your system
amountyesstringtwo decimal value like: "15.60"
customer_nameyesstringcustomer name being charged
customer_mobileyesstringinternationally formatted customer mobile
customer_emailyesstringcustomer valid email
descriptionyesstringcharge request description that represents the payment name
signatureyesstringsha-256 hash for the following concatenated params: merchant_code + merchant_reference_id + customer_merchant_profile_id + amount + hash_key
Both merchant_code and hash_key are being found in your API settings page in your cowpay dashboard
You can generate signatures while testing here

Request Payload Example

{
    "merchant_reference_id": "787856",
    "customer_merchant_profile_id": "253",
    "customer_name": "Test ing",
    "customer_mobile": "+201xxxxxxxxx",
    "customer_email": "gfalcon996@gmail.com",
    "amount":"15.00",
    "currency_code": "EGP",
    "signature": "fb7d24ca9f3929d360fd82196b6e2d765808ab1fb1c6df40ab4e2b2854630051",
    "description": "description"
}

Response

{
    "success": true,
    "status_code": 200,
    "status_description": "Operation done successfully",
    "type": "IFrame Initial Payment Request",
    "cowpay_reference_id": 1000249,
    "token": "466221e4c3530cd9628ec25ad301e370"
}

Using Iframe

Processing payments via iframes requires using cowpay iframes plugin to load the iframe by following the bellow instructions

embed the plugin in your web page

If you are testing on staging please replace cowpay.me with staging.cowpay.me to load the relevant script file.
<script src="https://cowpay.me/js/plugins/CCIframePlugin.js"></script>

Add an empty div element with id cowpay-iframe-container in your web page on which the plugin will be mounted

<div id="cowpay-iframe-container"></div>

The loaded script adds COWPAYIFRAMEDIALOG to your window global scope used to initiate and load the plugin

initiate and load the plugin

<script >
COWPAYIFRAMEDIALOG.init()
COWPAYIFRAMEDIALOG.load(token) // token value from the previous response 
</script>

listening to the order being processed in the browser

After the payment operation completed to plugin will post a message in the browser which you can use to take an extra action in your web page as below:

It's recommended to place your message event listener before initiating the plugin

window.addEventListener('message', function (e) {
    if (e.data && e.data.message_source === 'cowpay') {
        let paymentStatus = e.data.payment_status,
            cowpayReferenceId = e.data.cowpay_reference_id,
            gatewayReferenceId = e.data.payment_gateway_reference_id;
        
        // take an action based on the values 
    }
    
}, false);

COWPAYIFRAMEDIALOG.init()
COWPAYIFRAMEDIALOG.load(token) // token value from the previous response 

server callback

Your server will also receive a callback notification in order to update the payment status on your backend.