Manual Integration


Introduction

This guide allows advanced integrations with Moyasar by giving users a way to do custom implementations and designs.

This guide is only recommended for advanced users and if you prefer easy and straight forward integration we recommend that use the new Moyasar Payment Form

Overview

In this guide, we’ll see how to set up a basic payment form to accept credit/debit card payments.

We will also ensure a successful integration by saving the payment ID before redirecting the user to their bank page, then verify if the payment was successful after their return.

On this page

Before Starting

Before you start the integration process, make sure you complete these steps:

  1. Sign up for a Moyasar test account at https://dashboard.moyasar.com/session/signup
  2. Get your API Key. To authenticate your API request.

For more, refer to Get started with Moyasar.

For more details about used APIs in this tutorial, please refer to Moyasar API Docs

Due to security considerations, you are not allowed to post user details to your own server. We will demonstrate how to save the payment ID before redirecting the user to their bank.


Integrate Your Payment Form

We need to create a simple HTML form having two different sets of input fields:

  • Hidden input fields that are required to authenticate the payment request and provide amount and currency.
  • Visible input fields for user related data.

Here is the specification of the required data and fields to be included in the submission:

Step 1: Connect the HTML Payment Form

First, set your form’s action attribute to payment create endpoint URL, and set the method attribute to POST

<form accept-charset="UTF-8" action="https://api.moyasar.com/v1/payments.html" method="POST">
  <button type="submit">Pay</button>
</form>

You are not allowed to use any other action other than the one indicated earlier.


Step 2: Include Required Endpoint Fields

Next, we need to include some required hidden fields for making a payment, which are:

callback_url

After completing the transaction, your user will be redirected back to the specified URL.

  1. Add input of type hidden
  2. Set the input’s name to callback_url
  3. Set the value to the URL you want to redirect users to.
<input type="hidden" name="callback_url" value="https://www.my-store.com/payments_redirect" />
publishable_api_key

The publishable API key is used by Moyasar to identify you (the merchant) and complete the payment process. Including this key in public forms is safe, since it is only used to create payments and nothing else.

  1. Add an input of type hidden
  2. Set the input’s name to publishable_api_key
  3. Set the value to your publishable api key
<input type="hidden" name="publishable_api_key" value="your_publishable_api_key_here" />
amount

The amount you need to charge your user. It must be in the smallest currency unit. For example:

  • SAR (Saudi Riyal) has Halalah as its small unit (10 SAR = 1000 Halalah)
  • USD (US Dollar) has Cent as its small unit (10 USD = 1000 Cents)
  • KWD (Kuwaiti Dinar) has Fils as its small unit (10 KWD = 10000 Fils)
  • JPY (Japanese Yen) doesn’t have a small unit, so use it as is.
  1. Add an input of type hidden
  2. Set the input’s name to amount
  3. Set the value to the amount that you need charged.
<input type="hidden" name="amount" value="1000" />
currency [optional]

The currency is optional and defaults to SAR.

  1. Add an input of type hidden
  2. Set the input’s name to currency
  3. Set the value to the amount that you need charged.
<input type="hidden" name="amount" value="SAR" />
source[type]

This is used to specify the payment method and should be in this case set to creditcard to accept payments in Visa, Mastercard or Mada.

  1. Add input of type hidden
  2. Set the input’s name to source[type]
  3. Set the value to type of payment method
<input type="hidden" name="source[type]" value="creditcard" />
description [optional]

This is an optional field where you can add any notes you might need like as a description to the payment object.

  1. Add input of type hidden
  2. Set the input’s name to description
  3. Set the value of description
<input type="hidden" name="description" value="Order id 1234 by guest" />

Step 3: Include Payment Details Fields

Finally, we need a few visible elements to allow users to enter their payment details. Here are the required fields for credit card payments:

  • source[name] for card’s holder name.
  • source[number] for card’s number.
  • source[month] for card’s expiry month.
  • source[year] for card’s expiry year.
  • source[cvc] for card’s CVC.

Final code

<form accept-charset="UTF-8" action="https://api.moyasar.com/v1/payments.html" method="POST">

    <input type="hidden" name="callback_url" value="https://www.my-store.com/payments_redirect" />
    <input type="hidden" name="publishable_api_key" value="your publishable api key here" />
    <input type="hidden" name="amount" value="10000" />
    <input type="hidden" name="source[type]" value="creditcard" />
    <input type="hidden" name="description" value="Order id 1234 by guest" />

    <input type="text" name="source[name]" />
    <input type="text" name="source[number]" />
    <input type="text" name="source[month]" />
    <input type="text" name="source[year]" />
    <input type="text" name="source[cvc]" />

    <button type="submit">Purchase</button>
</form>

Submitting Form

The form can be submitted through the basic HTML form described above, or using Javascript which allows us save the payment ID before redirecting the user.

The following code sample will show how to submit payment details to Moyasar while saving the ID before redirecting to user’s bank.

For this we need to do the following:

  • Handle form’s submit event and prevent default event handling.
  • Serialize form data.
  • Send a POST request to Moyasar using Javascript.
  • Handle the JSON response, then redirect the user to their bank’s page.

jQuery Example

// Capture the form submit button
$("#submit_button_id").click(function(event) {
    // Prevent default browser behavior
    event.preventDefault();

    // Serialize data
    var form_data = $("#form_id").serialize();

    // Send the POST request to Moyasar
    $.ajax({
        url: "https://api.moyasar.com/v1/payments",
        type: "POST",
        data: form_data,
        dataType: "json",
    })
    // uses `.done` callback to handle a successful AJAX request
    .done(function(data) {
        // Grab the payment ID
        var paymentId = data.id;
        // ... save your ID somewhere save in your backend.

        // Redirect the user to the bank page.
        window.location.href = data.source.transaction_url;
    });
});

Error handling is not shown in this example. In case of an error, Moyasar will return a 4xx status code. Please refer to the API Docs for more information about errors.


Verify the Payment

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

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

Fetch the payment using its ID though the API, and verify its status, amount and currency before accepting or placing any user’s purchase.

Or, using ID we have saved in the Javascript example, perform the same verifications.


Last Modified : May 2021