Close
    logo

    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
    No redirection
    Prebuilt
    Fast & easy integration
    Hosted Payment Page
    Redirection
    Prebuilt
    Fast & easy integration

    I-frame and Kashier-hosted payment page are both PCI Compliant, and support the same range of payment methods.

    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.
    Fill in your order attributes, then add the following code snippet to your website.
    Click here to expandClick here to shrink
    1<script
    2 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></script>

    Parameters

    ParametersDescriptionRequired
    data-amount (string)Order amount 100TRUE
    data-hash (string)Order hash generated in HashingTRUE
    data-currency (string)Order currency EGPTRUE
    data-orderId (string)Unique Order IdentifierTRUE
    data-merchantId (string)Merchant account number or merchant ID MID-123-123TRUE
    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_installmentsFALSE
    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. Webhookfalse
    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 TRUEFALSE
    data-paymentRequestId (string)Using in case of linking the transaction with originFALSE
    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 externalTRUE
    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 enTRUE

    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.
    Fill in your order attributes, then add the following code snippet to your website.
    Click here to shrink
    1<a
    2 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"
    19></a>

    Parameters

    ParametersDescriptionRequired
    amount (string)Order amount 100TRUE
    hash (string)Order hash generated in HashingTRUE
    currency (string)Order currency EGPTRUE
    orderId (string)Unique Order IdentifierTRUE
    merchantId (string)Merchant account number or merchant ID MID-123-123TRUE
    mode (string)Mode test or live, mode=testTRUE
    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 charactersFALSE
    allowedMethods (string)To determine allowed payment method by default all payment method is allowed card,bank_installmentsFALSE
    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 Webhookfalse
    redirectMethod (string)The Redirection method after payment, using get or post formdata in case of Redirection, Default method is get, ex:- redirectMethod=postFALSE
    failureRedirect (string)To choose to redirect after first payment failure or not. Its value is TRUE OR FALSE, Default value is TRUEFALSE
    paymentRequestId (string)Using in case of linking the transaction with originFALSE
    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 externalTRUE
    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 enTRUE

    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:

    you can obtain your API KEY from Dashboard.


    Click here to shrink
    1//Copy and paste this code in your Backend
    2let crypto = require('crypto');
    3function generateKashierOrderHash(order) {
    4 const mid = 'MID-123-123'; //your merchant id
    5 const amount = order.amount; //eg: 22.00
    6 const currency = order.currency; //eg: "EGP"
    7 const orderId = order.merchantOrderId; //eg: 99
    8 const secret = 'yourApiKey';
    9 const path = `/?payment=${mid}.${orderId}.${amount}.${currency}`;
    10
    11 const hash = crypto.createHmac('sha256', secret).update(path).digest('hex');
    12 return hash;
    13}
    14//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&currency=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 shrink
    1function 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');
    9
    10 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

    ParameterDescription
    paymentStatusStatus of transaction is either SUCCESS OR FAILURE
    cardDataTokenYour shopper’s card token using in future and recurring payment.
    maskedCardmaskedCard of your customer
    merchantOrderIdYour order identifier using in Order Rseconciliation
    orderIdKashier system identifier of order
    cardBrandcard brand (sometimes called a card network or association)
    transactionIdYou transaction identifier
    currencyOrder currency
    signatureOrder signature to ensure that connection between your server and kashier is secure.
    modeMode 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.

    You can retrive your order details using Order Rseconciliation, Also if your transaction is failed, You can know the reason of failed transaction in your order by mapping transactionResponseCode of your transaction with Payment Reason Code

    Demo

    You can download and install our integration Demo

    Features — Previous
    Connected Accounts
    Next — Payment
    Payment UI Builder