Skip to main content

Basic Integration

This page will guide you to accept mada, Visa, Mastercard and American Express payments using our Payment Form Javascript library.

Before Starting​

Before you start accepting credit/debit card payments, make sure you complete these steps first:

  1. Sign up for a Moyasar account on our dashboard.
  2. Get your publishable API key to authenticate your form payment requests.

Including Moyasar Form​

Moyasar Form is a lightweight Javascript library that will take care of creating the payment components within your website using a modern and responsive design.

The current up-to-date version of the library is 1.15.0 which can be used through the official Moyasar CDN server:

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

You can start the integration by including the following tags within the <head> tag of your page:

HTML
<link rel="stylesheet" href="https://cdn.moyasar.com/mpf/1.15.0/moyasar.css" />
<script src="https://cdn.moyasar.com/mpf/1.15.0/moyasar.js"></script>

Initiating the Payment Form​

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

HTML
<div class="mysr-form"></div>
<script>
  window.Moyasar.init({
    element: '.mysr-form',
    // 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,
    currency: 'SAR',
    description: 'Coffee Order #1',
    publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',
    callback_url: 'https://moyasar.com/thanks',
    methods: ['creditcard'],
  });
</script>

Configuration Keys​

FieldDescription
amountPayment amount which should be positive integer representing the smallest currency unit (e.g., 100 Halala to charge 1.00 SAR or 100 to charge ¥100, a zero-decimal currency). The minimum value is 100.
currency3-letter ISO Code for currency. E.g., SAR, CAD.
descriptionAn arbitrary string that you can attach to a payment object. Payment description is only for your reference and it is not displayed to your users.
publishable_api_keyYour publishable API key, learn more on how to get the key here.
callback_urlURL of your website page to be redirected to after the customer completes a transaction. (e.g., https://example.com/orders).
methodsThis is used to enable and disable payment methods on the form. By default, all the methods are enabled creditcard, applepay and stcpay.

Learn more about available configuration keys here form configuration.

Payment Form​

Save 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 user's connection drops.

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

Option 1: URL​

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

JS
Moyasar.init({
  element: '.mysr-form',
  amount: 1000,
  currency: 'SAR',
  description: 'Coffee Order #1',
  publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',
  callback_url: 'https://moyasar.com/thanks',
  methods: ['creditcard'],
  on_completed: '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.

Important

If any other status code is returned, a network connection error will appear, and redirection to 3D Secure will be aborted.

Option 2: Callback Function​

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 or use async/await.

JS
Moyasar.init({
  element: '.mysr-form',
  amount: 1000,
  currency: 'SAR',
  description: 'Coffee Order #1',
  publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',
  callback_url: 'https://moyasar.com/thanks',
  methods: ['creditcard'],
  on_completed: async function (payment) {
    await savePaymentOnBackend(payment);
  },
});

The method savePaymentOnBackend is a placeholder and you must provide your own custom logic.

Step 4: Verify Payment​

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:

Callback URL
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, just show success or failure according to the previous validation.

Payment Flow​