Web Payments


Introduction

Overview

Integrating with systems can be tricky and not straight forward sometimes, that is why Moyasar made it its own mission to connect merchants and customers with simple yet powerful financial solutions.

Merchants can add payments in no time with our new Payment Form with as little as one function call. The new form unlocks a lot of features and possiblites for our client by providing a complete set validations for all inputs which can ensure successful customer transactions with a slick and simple UI that focus on customers experience and ease of use.

We also give you different payment options that range from a 1-Click like Apple Pay to a couple of keystrokes to accept traditional credit card payments.

In this guide we will help you go through the process of setting up the Payment Form in your website and start accepting payments within no time.

We will also guide you through all the best practices you need to ensure a successful and secure payment process.

On this page

Before Starting

Before you start integrating the Payment Form, make sure you complete these steps first:

  1. Sign up for a Moyasar account at https://dashboard.moyasar.com/.
  2. Get your Publishable API Key. To authenticate your form payment requests.

For more, refer to Get started with Moyasar.


Simple Integration

Moyasar Form is a lightweight Javascipt library, that can get you up and running pretty quick. The current up to date version of the library is 1.5.0 which can be used through the official Moyasar CDN server:

  • https://cdn.moyasar.com/mpf/1.5.0/moyasar.js
  • https://cdn.moyasar.com/mpf/1.5.0/moyasar.css

You can start the integration by including the previous URLs in the head section of your website as follows:

<head>
    <!-- Other Tags -->

    <!-- Moyasar Styles -->
    <link rel="stylesheet" href="https://cdn.moyasar.com/mpf/1.5.0/moyasar.css">

    <!-- Moyasar Scripts -->
    <script src="https://polyfill.io/v3/polyfill.min.js?features=fetch"></script>
    <script src="https://cdn.moyasar.com/mpf/1.5.0/moyasar.js"></script>

    <!-- Download CSS and JS files in case you want to test it locally, but use CDN in production -->
</head>

Once you decide on a good place for the form, add an empty <div> tag and then invoke the init method on our global Moyasar class.

<div class="mysr-form"></div>
<script>
    Moyasar.init({
        // Required
        // Specify where to render the form
        // Can be a valid CSS selector and a reference to a DOM element
        element: '.mysr-form',

        // Required
        // Amount in the smallest currency unit
        // For example:
        // 10 SAR = 10 * 100 Halalas
        // 10 KWD = 10 * 1000 Fils
        // 10 JPY = 10 JPY (Japanese Yen does not have fractions)
        amount: 1000,

        // Required
        // Currency of the payment transation
        currency: 'SAR',

        // Required
        // A small description of the current payment process
        description: 'Coffee Order #1',

        // Required
        publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',

        // Required
        // This URL is used to redirect the user when payment process has completed
        // Payment can be either a success or a failure, which you need to verify on you system (We will show this in a couple of lines)
        callback_url: 'https://moyasar.com/thanks',

        // Optional
        // Required payments methods
        // Default: ['creditcard', 'applepay', 'stcpay']
        methods: [
            'creditcard',
        ],
    });
</script>

The form uses our Payment APIs to perform required actions, you can learn more about it on Moyasar API Docs.

Additional configuration keys can be found here on Advanced Configurations.


Here is the resulting form:

When a user click on the pay button, their payment details will be sent securely to Moyasar servers and then processed, after that the user will be redirected the 3-D Secure page for validation, leading to the last step, the user will be redirected back to the URL specified in callback_url.

Saving Payment ID

This step is optional but highly recommended to save the payment ID before redirecting the user to 3-D Secure, which grants you the ability to verify payment details in case your users connection drop.

To save the payment ID you can provide the on_complete configuration option with a URL, or a callback function.

When providing a URL the library will make a POST request containing the payment object, here is an example:

{
    on_complete: 'https://mystore.com/checkout/savepayment'
}

The URL can be anything you choose, but keep in mind your endpoint must return a 201 Created HTTP status code for the form to proceed. If any other status code returned, the form will abort redirection.

The other option is to provide a callback function, and due to the asynchronous nature of JavaScript, you need to return a Promise object which lets the form wait until your task is completed.

{
    on_complete: function (payment) {
        return new Promsie(function (resolve, reject) {
            // This is just an example, provide anything you want here
            $.ajax({
                type: 'POST',
                url: 'https://mystore.com/checkout/savepayment',
                data: payment,
                dataType: 'json'
                success: function (data, textStatus, jqXHR) {
                    // An empty dictionary/object is required to indicate to the form everything is good to go
                    resolve({});
                },
                error: function (jqXHR, textStatus, errorThrown) {
                    reject();
                }
            });
        });
    }
}

Payment Verification

Once the user has completed the payment, and got redirected to your website or app using the callback_url you provided earlier, the following HTTP query parameters will be appended:

  • id
  • status
  • message

Here is an example:

https://www.my-store.com/payments_redirect?id=79cced57-9deb-4c4b-8f48-59c124f79688&status=paid&message=Succeeded

Now fetch the payment using its id through our Fetch API, and verify its status, amount and currency before accepting your user’s order or completing any business action.

Next, either show succuss or failure according to the previous validation.

Apple Pay

Apple Pay integration is made seemless with Moyasar Form. All required is to provide a couple of options and you are all set. But first, you need to set up your Apple Developer account, generate the required certificates and let our team activate this method for you.

Here is the basic setup:

{
    methods: [
        'creditcard',
        'applepay'
    ],
    apple_pay: {
        country: 'SA',
        label: 'Awesome Cookie Store',
        validate_merchant_url: 'https://mystore.com/checkout/applepay/validate-merchant',
    }
}

The form expects the endpoint specified at validate_merchant_url config key to accept a POST request and read validation_url item from the JSON body.

Here is a sample request:

POST /checkout/applepay/validate-merchant HTTP/1.1
Host: mystore.com
Content-Type: application/json
Content-Length: 74

{
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/paymentSession"
}

Now you must use the provided URL perfom the merchant validation then return the Apple Response as is with Content-Type: application/json header. The header is required in order for the form to work correctly.

STC Pay

After activating STC Pay on your account, you can just add it to the available methods and voila.

methods: [
    'creditcard',
    'stcpay'
],

Last Modified : Sep 2021