Advanced Configurations


Payment Form Configurations

Here is a list of acceptable configurations values/options for the form.

On this page

Element

Required

Element must be a valid CSS selector for the target element for form to be mounted in. Or can be an instance of DOM element Element. Here is an example:

element: '.payment-form', // Using a class
element: '#payment-form', // Using an ID
element: document.querySelector('.payment-form'), // or just providing an Element instance

Language

Optional

This option can be used to set display language for the form. If left empty, language will be inferred from <html> element then fallback to en if it cannot be inferred. Here is an example

language: 'en', // Displaying the form in English
language: 'ar', // Displaying the form in Arabic
language: 'fr', // Displaying the form in French (You need to provide your own translations)

Translations

Optional

This option is used to add more translations to the form. Here is an example:

translations: {
    fr: {
        "validation.should_be_english_letters_only": "Le nom ne peut avoir que l'alphabet anglais et des espaces",
        "validation.first_and_last_name_required": "Le prénom et le nom de famille sont obligatoires",
    }
},

Publishable API Key

Required

The publishable API key is required in order to communicate with Moyasar’s API and complete the payment request. Here is an example:

You can get both keys from your account at Moyasar Dashboard

// Live key is used in production environemnt and will require a valid SSL certificate
publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',

// This will put the form in testing mode and allow you to test without an SSL certificate
publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',

Payment Methods

Optional

This is used to enable and disable payment methods on the form. By default, all the methods are enabled, which are:

  • Credit Card (creditcard)
  • Apple Pay (applepay)
  • STC Pay (stcpay)
// Enabling only Credit Card and Apple Pay
methods: [
    'creditcard',
    'applepay'
]

Amount

Required

This sets the amount for user to pay. Amount must be in minor unit of selected currency, e.g. if we want to get a payment of $10 then we must represent the amount in cents 1000. Here is an example:

amount: 1000

Currency

Required

This sets which currency is used for the amount to be paid. Here is an example:

currency: 'USD', // Get payment in US Dollars
currency: 'SAR', // Get payment in Saudi Riyals
currency: 'JPY', // Get Payment in Japanese Yen

The currency must be in ISO 3166-1 alpha-3 country code format.

Description

Required

This option is used to set a description to be sent along other payment information to Moyasar’s API. Here is an example:

description: 'Payment for Order #34321'

The description can be any string you want.

Callback URL

Required

This URL is used by Moyasar to redirect the user back after the payment is either successful, or the user has completed 3D stage.

callback_url: 'https://example.com/payment/return'

Metadata

Optional

Adds searchable key/value pairs to the payments.

metadata: {
    'order_id': '10039'
}

Supported Networks

Optional

This optional configuration option is used to set accepted card networks in the form. The default value is all networks except amex.

Supported Networks:

  • Mada (mada)
  • Visa (visa)
  • Mastercard (mastercard)
  • American Express (amex)

Example:

supported_networks: [
    'mada',
    'visa',
    'mastercard',
    'amex'
],

Fixed Width

Optional

This option is used to limit the form width to only 360px and it is enabled by default. To disable this just set it to false.

Example:

fixed_width: false,

On Initiating

Optional

This callback is used to handle the event when a user starts a payment method and before any information is sent to Moyasar’s API. You can use this to perform any last second validations or to prepare something.

When you handle this event, you can return a false to stop the payment process, or a dictionary that is either empty or contains description or callback_url values to update the form configurations if you need to.

If you need to do a long-running process, you can return a Promise that returns either of the mentioned values before.

Here is an example to stop the form from submitting:

on_initiating: function () {
    if (somethingIsWrong) {
        return false;
    }
}

Using a Promise:

on_initiating: function () {
    return new Promise(function (resolve, reject) {
        if (somethingIsWrong) {
            resolve(false);
            return;
        }
    });
}

Make the form proceed:

on_initiating: function () {
    return {};
}

Using a Promise:

on_initiating: function () {
    return new Promise(function (resolve, reject) {
        resolve({});
    });
}

On Completed

Optional

This event is fired when a payment is created by Moyasar’s API. You can, intercept the payment to save it or do any other processing.

This option can either take a URL and the payment object will be posted to. The endpoint must return 201 for the form to proceed, or the form will be aborted.

You can also provide a callback that returns a void or a Promise if you need a long-running task.

Example:

on_completed: function (payment) {
    // Do stuff with payment object
}

Using a Promise:

on_completed: function (payment) {
    return new Promise(function (resolve, reject) {
        // savePayment is just an example, your usage may vary.
        if (savePayment(payment)) {
            resolve();
        } else {
            reject();
        }
    });
}

On Failure

Optional

This event is used to handle payment failure, you will get a string if there is an error.

Example:

on_failure: function (error) {
    // Handle error
}

On Redirect

Optional

When the form finishes it work and is about to redirect the user, you can intercept this action and handle redirection manually. Here is an example:

on_redirect: function (url) {
    // Handle redirection manually
}

Apple Pay Configurations

Required if Apple Pay is Activated

This is an object that contains Apple Pay specific configurations. Here is an example:

apple_pay: {
    // Apple Pay Configurations
}

Version

Optional

This is used to specify Apple Pay JS version. Default is 6. Here is an example:

apple_pay: {
    version: 7
}

Country

Required

Apple Pay merchant country.

apple_pay: {
    country: 'SA'
}

Merchant Capabilities

Optional

Merchant capabilities to activate for this Apple Pay session. Default is:

apple_pay: {
    merchant_capabilities: [
        'supports3DS',
        'supportsCredit',
        'supportsDebit'
    ],
},

Label

Required

Label to be displayed in the payment modal. Here is an example:

apple_pay: {
    label: 'Ali Hardware Store'
}

Merchant Validation URL

Required

This URL is used to initiate the Apple Pay session. A POST request will made to the specified endpoint with a JSON object containing the URL. Here is the JSON snippet:

{
    "validation_url": "https://url.to.applepay.tld/something/somthing"
}

The endpoint must return a response with the header Content-Type: application/json and the response return from Apple as is.

Here is the configuration example:

apple_pay: {
    validate_merchant_url: 'https://mystore.test/applepay/validate-merchant'
}

Supported Countries (supported_countries) [Optional]

An array of countries that cards are allowed from.

Default: ['SA']. Only Saudi Arabia is enabled by default to prevent fraudulent transactions, you may enable more countries at your own risk.

apple_pay: {
    supported_countries: ['SA', 'US']
}

Advanced Integration

If the form does not satisfy your needs, you can always build your own integration solution here.


Last Modified : Sep 2021