Payment UI
Payment UI creates a secure, pre-built UI that lets you collect payments quickly. It works across devices and can help increase your conversion.
Kashier offers two pre-built UI solutions for accepting payments:
I-frame and Kashier-hosted payment page are both PCI Compliant, and Wallets, bank installments, valU, cards, and fawry are all available options
I-frame
The i-frame is a checkout popup window which opens on-top of your payment page. This method is recommended if you prefer a fast and easy way of integration without any customizations.
The i-frame is a prebuilt payment form, which is easy to integrate in only 4 steps. You can test the form by generating a Test API Key. Learn more about API keys.
Display i-frame by adding the next snippet to your website.
Click here to expandClick here to shrink1<script2 id="kashier-iFrame"3 src="https://checkout.kashier.io/kashier-checkout.js"4 data-amount="ORDER-AMOUNT"5 data-hash="ORDER-HASH"6 data-currency="ORDER-CURRENCY"7 data-orderId="ORDER-ORDERID"8 data-merchantId="ORDER-MERCHANTID"9 data-merchantRedirect="ORDER-MERCHANTREDIRECT"10 data-serverWebhook="ORDER-WEBHOOK-URL"11 data-mode="ORDER-MODE"12 data-metaData="ORDER-METADETA"13 data-description="ORDER-DESCRIPTION"14 data-allowedMethods="ORDER-ALLOWEDMETHODS"15 data-defaultMethod="ORDER-DEFAULTMETHOD"16 data-redirectMethod="ORDER-REDIRECTMETHOD"17 data-failureRedirect="ORDER-FAILUREREDIRECT"18 data-paymentRequestId="ORDER-PAYMENTREQUESTID"19 data-connectedAccount="ORDER-CONNECTEDACCOUNT"20 data-type="ORDER-TYPE"21 data-brandColor="ORDER-brandColor"22 data-display="ORDER-DISPLAY"23 data-manualcapture="ORDER-AUTH"24 data-customer="Customer-Data"25 data-saveCard="Saving-card"26 data-interactionSource="Ecommerce"27 data-enable3DS="true"28></script>
Parameters
| Parameters | Description | Required |
|---|---|---|
| data-amount (string) | Order amount 100 | TRUE |
| data-hash (string) | Order hash generated in Hashing | TRUE |
| data-currency (string) | Order currency EGP | TRUE |
| data-orderId (string) | Unique Order Identifier | TRUE |
| data-merchantId (string) | Merchant account number or merchant ID MID-123-123 | TRUE |
| data-mode (string) | Mode to be test or live, data-mode="test" | TRUE |
| data-metaData (string) | order meta data must be encoded JSON String. So you should pass it to stringify function to convert it from object (constructing from keys and values) to JSON String then you should also encode the result of JSON.stringify, encodeURIComponent(JSON.stringify({'email':'email@gmail.com'})) | FALSE |
| data-description (string) | order description should be less than 120 characters. | FALSE |
| data-allowedMethods (string) | To determine allowed payment method by default all payment method is allowed card,bank_installments,wallet,fawry | FALSE |
| data-defaultMethod (string) | To determine which method you want PaymentUI to open on it, By default PaymentUI opens on card method. data-defaultMethod accept the following pattern "method,provider/abbreviation". Example, you want PaymentUI to open on installment method, so data-defaultMethod value should be bank_installments. But if you want to open PaymentUI on certian instalment plans of NBE bank the value of data-defaultMethod should be bank_installments,NBE. | FALSE |
| data-merchantRedirect (string) | data-merchantRedirect should be "URI encoded. Learn more about Redirect urlencode(https://www.your_website.com/redirect) | TRUE |
| data-serverWebhook (string) | Pass an endpoint to receive server-to-server notification on your application is as easy as creating a new page that accepts unauthenticated POST requests. The event object is sent as JSON in the request body. Webhook | false |
| data-redirectMethod (string) | The Redirection method after payment, using get or post formdata in case of Redirection, Default method is get, ex:- data-redirectMethod="post" | FALSE |
| data-failureRedirect (string) | To choose to redirect after first payment failure or not. Its value is TRUE OR FALSE, Default value is TRUE | FALSE |
| data-paymentRequestId (string) | Using in case of linking the transaction with origin | FALSE |
| data-connectedAccount (string) | Using in case of make a payments on behalf of your Connected Account by passing Sub Merchant/Connected Account Merchant Id to data-connectedAccount attribute. data-connectedAccount="MID-452-644" | FALSE |
| data-type (string) | Using to determine type of kashier origin, Default value must be external | TRUE |
| data-brandColor (string) | You can set your branding color by passing hexadecimal color as data-brandColor='#0', Also you can set opacity by setting rgba as data-brandColor='rgba(45, 164, 78, 0.9)', By default the branding color is rgba(45, 164, 78, 0.9) | FALSE |
| data-display (string) | Display language of i-frame allowed language is either ar or en | TRUE |
| data-manualCapture (bool) | TRUE : The authorization step is first, and then the amount is captured/released with AUTH&CAP, False: Directly capturing without authorization | FALSE |
| data-customer (string) | The purpose is to save the customer's card so that they can pay again. Referencing is required, and all other options are optional. The result should be encoded JSON.stringify, JSON.stringify({"reference":"1","firstName":"firstName","lastName":"lastName", "email": "example@gmail.com}) So you should pass it to save customer card to pay it again , you can pay with token | FALSE |
| data-saveCard (string) | The purpose is to save credit card information, whether it's "optional" where the user has the option to save it by checking a box or "forced" where the card information is saved without the customer's choice. It's done automatically can | FALSE |
| data-interactionSource (string) | it must be MOTO orECOMMERCE in case you use token or save card in paymentUI to pay again based on the business case. data-saveCard and data-customer will be required in this case | FALSE |
| data-enable3DS (bool) | in case pay with saved card to pay direct without 3ds so should be enabled false atherwise true | FALSE |
Hosted Payment Page
The Hosted Payment Page is a payment form with a redirection checkout experience. This form is built for merchants without platforms, interested in a fast and easy method integration.
The Hosted Payment Page is designed for businesses that manage their product catalogs in a system outside of Kashier and just need a checkout page where payments are processed by Kashier.
Display hosted payment page by adding the next snippet to your website.
Click here to expandClick here to shrink1<a2 href="https://checkout.kashier.io/?merchantId=YOUR-MERCHANT-ACCOUNT-ID&3orderId=ORDER-ID&4amount=ORDER-AMOUNT&5currency=ORDER-CURRENCY&6hash=ORDER-HASH&7mode=ORDER-MODE&8merchantRedirect=YOUR-SUCCESS-REDIRECT-URL&9serverWebhook=YOUR-WEBHOOK-URL&10metaData=ORDER-META-DATA&11paymentRequestId=ORDER-PAYMENTREQUESTID&12allowedMethods=ORDER-ALLOWED-METHODS&13defaultMethod=ORDER-DEFAULT-METHOD&14failureRedirect=ORDER-FAILURE-REDIRECT&15redirectMethod=ORDER-REDIRECT-METHOD&16connectedAccount=ORDER-CONNECTED-ACCOUNT&17brandColor= ORDER-BRAND-COLOR&18display=ORDER-DISPLAY&19manualCapture=ORDER-AUTH&20customer=Customer-data&21saveCard=customer-saveCard&22interactionSource=Ecommerce&23enable3DS=true24"25></a>
Parameters
| Parameters | Description | Required |
|---|---|---|
| amount (string) | Order amount 100 | TRUE |
| hash (string) | Order hash generated in Hashing | TRUE |
| currency (string) | Order currency EGP | TRUE |
| orderId (string) | Unique Order Identifier | TRUE |
| merchantId (string) | Merchant account number or merchant ID MID-123-123 | TRUE |
| mode (string) | Mode test or live, mode=test | TRUE |
| metaData (string) | must be encoded JSON String. So you should pass it to stringify function to convert it from object (constructing from keys and values) to JSON String then you should also encode the result of JSON.stringify, encodeURIComponent(JSON.stringify({'email':'email@gmail.com'})) | FALSE |
| description (string) | order description should be less than 120 characters | FALSE |
| allowedMethods (string) | To determine allowed payment method by default all payment method is allowed card,bank_installments,wallet,fawry | FALSE |
| defaultMethod (string) | To determine which method you want PaymentUI to open on it, By default PaymentUI opens on card method. defaultMethod accept the following pattern "method,provider/abbreviation". Example, you want PaymentUI to open on installment method, so defaultMethod value should be bank_installments. But if you want to open PaymentUI on certian instalment plans of NBE bank the value of defaultMethod should be bank_installments,NBE. | FALSE |
| merchantRedirect (string) | merchantRedirect should be "URI encoded. Learn more about Redirect urlencode(https://www.your_website.com/redirect) | TRUE |
| serverWebhook (string) | Pass an endpoint to receive server-to-server notification on your application is as easy as creating a new page that accepts unauthenticated POST requests. The event object is sent as JSON in the request body. Learn more about Webhook | false |
| redirectMethod (string) | The Redirection method after payment, using get or post formdata in case of Redirection, Default method is get, ex:- redirectMethod=post | FALSE |
| failureRedirect (string) | To choose to redirect after first payment failure or not. Its value is TRUE OR FALSE, Default value is TRUE | FALSE |
| paymentRequestId (string) | Using in case of linking the transaction with origin | FALSE |
| connectedAccount (string) | Using in case of make a payments on behalf of your Connected Account by passing Sub Merchant/Connected Account Merchant Id to connectedAccount attribute. connectedAccount="MID-452-644" | FALSE |
| type (string) | Using to determine type of kashier origin, Default value must be external | TRUE |
| data-brandColor (string) | You can set your branding color by passing hexadecimal color as brandColor= encodeURIComponent("#0"), Also you can set opacity by setting rgba as brandColor= encodeURIComponent("rgba(45, 164, 78, 0.9)"), By default the branding color is rgba(45, 164, 78, 0.9) | FALSE |
| display (string) | Display language of hpp allowed language is either ar or en | TRUE |
| manualCapture (bool) | TRUE : The authorization step is first, and then the amount is captured/released with AUTH&CAP, False: Directly capturing without authorization | FALSE |
| customer (string) | The purpose is to save the customer's card so that they can pay again. Referencing is required, and all other options are optional. The result should be encoded JSON.stringify, JSON.stringify({"reference":"1","firstName":"firstName","lastName":"lastName", "email": "example@gmail.com}) So you should pass it to save customer card to pay it again , you can pay with token | FALSE |
| saveCard (string) | The purpose is to save credit card information, whether it's "optional" where the user has the option to save it by checking a box or "forced" where the card information is saved without the customer's choice. It's done automatically can | FALSE |
| interactionSource (string) | it must be MOTO orECOMMERCE in case you use token or save card in paymentUI to pay again based on the business case. data-saveCard and data-customer will be required in this case | FALSE |
| enable3DS (bool) | in case pay with saved card to pay direct without 3ds so should be enabled false atherwise true | FALSE |
Hashing
Kashier uses hashing to ensure that Payment UI and responses shared between your application and Kashier over network have not been tampered with. We use SHA256 hashing to ensure the safety of transaction data.
The Order Hash is used to validate your order with what your customers are paying. Order hash generation uses HMAC SHA256 Crypto mechanism, you should generate the hash from your backend and is implemented as explained below:
Click here to shrink1//Copy and paste this code in your Backend2let crypto = require('crypto');3function generateKashierOrderHash(order) {4 const mid = 'MID-123-123'; //your merchant id5 const CustomerReference = '1'; //your customer id to save card67 const amount = order.amount; //eg: 22.008 const currency = order.currency; //eg: "EGP"9 const orderId = order.merchantOrderId; //eg: 9910 const secret = 'yourApiKey';11 const path = `/?payment=${mid}.${orderId}.${amount}.${currency}${CustomerReference? ('.'+ CustomerReference): null}`;1213 const hash = crypto.createHmac('sha256', secret).update(path).digest('hex');14 return hash;15}16//The Result Hash for /?payment=mid-0-1.99.20.EGP with secret 11111 should result 606a8a1307d64caf4e2e9bb724738f115a8972c27eccb2a8acd9194c357e4bec
Please note that for creating hash use only the parameters mentioned in the snippet above, don't add extra parameters in the hash creation.
Verify Transaction
If the transaction is complete, Kashier will redirect the user back to a redirect url you set in data-merchantRedirect. We'll append the transaction response in the URL. In the example above, the user will be redirected to http://your_website.com/redirect?paymentStatus=FAILURE&cardDataToken=f5b2ef3a-a707-4899-a00c-52dcc248e165&maskedCard=512345******2346&merchantOrderId=74_1653325496&orderId=8177e0e9-c6ac-4404-8da8-00db683eb1f2&cardBrand=Mastercard&orderReference=TEST-ORD-193320144&transactionId=TX-35524543539&amount=106¤cy=USD&signature=e7bdb91ff23bf097402c75a9a40c2d58ed3a742e26adcee2f6689745047670a7&mode=test if you using GET method.
Please note that for creating hash use only the parameters mentioned in the snippet above, don't add extra parameters in the hash creation.
Signature
Once the transaction is processed, Kashier creates a signature with response parameters and sends it in the redirection along with other parameters.
You need to validate the signature which is appended to the redirection url. For validating the Signature in the response, use function as explained below in validating the Signature.
Click here to shrink1function validateSignature(query, secret) {2 let queryString = '';3 for (let key in query) {4 if (key == 'signature' || key == 'mode') continue;5 queryString = queryString + '&' + key + '=' + query[key];6 }7 let finalUrl = queryString.substr(1);8 const signature = crypto.createHmac('sha256', secret).update(finalUrl).digest('hex');910 if (signature == query.signature) return true;11 else return false;12}
Handle Webhook
When a payment is successful, Kashier sends a payment webhook event to webhook URL that you provide. Learn more about using webhooks.
Redirect
Kashier sends the response of the transaction on the redirect url sent by the merchant.
The URL in the format https://your_websire.com/redirect can be sent in data-merchantRedirect parameter in Payment UI.
Below are the parameters you can include in Payment UI solution's Redirect URL.
Parameters
| Parameter | Description |
|---|---|
| paymentStatus | Status of transaction is either SUCCESS OR FAILURE |
| cardDataToken | Your shopper’s card token using in future and recurring payment. |
| maskedCard | maskedCard of your customer |
| merchantOrderId | Your order identifier using in Order Rseconciliation |
| orderId | Kashier system identifier of order |
| cardBrand | card brand (sometimes called a card network or association) |
| transactionId | You transaction identifier |
| currency | Order currency |
| signature | Order signature to ensure that connection between your server and kashier is secure. |
| mode | Mode test or live |
click here to learn how to validate signature to ensure that Payment UI and responses shared between your application and Kashier over network have not been tampered with.
Demo
You can download and install our integration Demo