Payments
Form Configuration

34min
Overview
Here is a list of acceptable configuration values/options for the form.
Element (required)
﻿The element must be a valid CSS selector for the target element for the form to be mounted. Or can be an instance of a DOM element Element. Here is an example:
JS
element: '.payment-form', // Using a class
element: '#payment-form', // Using an ID
element: document.querySelector('.payment-form'), // or just providing an Element instance
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 the 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
JS
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)
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:
JS
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",
    }
},
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﻿
JS
// Live key is used in production environemnt and will require a valid SSL certificate
publishable_api_key: 'pk_live_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',

// This will put the form in testing mode and allow you to test without an SSL certificate
publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',
// Live key is used in production environemnt and will require a valid SSL certificate
publishable_api_key: 'pk_live_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)
JS
// Enabling only Credit Card and Apple Pay
methods: [
    'creditcard',
    'applepay',
]
// Enabling only Credit Card and Apple Pay
methods: [
    'creditcard',
    'applepay',
]
﻿
Amount (required)
This sets the amount for the user to pay.
The amount must be in a 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.
JS
amount: 1000
amount: 1000
﻿
Currency (required)
This sets which currency is used for the amount to be paid.
JS
currency: 'USD', // Get payment in US Dollars
currency: 'SAR', // Get payment in Saudi Riyals
currency: 'JPY', // Get Payment in Japanese Yen
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 with other payment information
to Moyasar's API.
JS
description: 'Payment for Order #34321'
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 the 3D Secure stage.
JS
callback_url: 'https://example.com/payment/return'
callback_url: 'https://example.com/payment/return'
﻿
Metadata (optional)
Adds searchable key/value pairs to the payments.
JS
metadata: {
    'order_id': '10039'
}
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)
JS
supported_networks: [
    'mada',
    'visa',
    'mastercard',
    'amex'
],
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.
JS
fixed_width: false,
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 a 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:
JS
on_initiating: function () {
    if (somethingIsWrong) {
        return false;
    }
}
on_initiating: function () {
    if (somethingIsWrong) {
        return false;
    }
}
﻿
Using a Promise:
JS
on_initiating: function () {
    return new Promise(function (resolve, reject) {
        if (somethingIsWrong) {
            resolve(false);
            return;
        }
    });
}
on_initiating: function () {
    return new Promise(function (resolve, reject) {
        if (somethingIsWrong) {
            resolve(false);
            return;
        }
    });
}
﻿
Make the form proceed:
JS
on_initiating: function () {
    return {};
}
on_initiating: function () {
    return {};
}
﻿
Using a Promise:
JS
on_initiating: function () {
    return new Promise(function (resolve, reject) {
        resolve({});
    });
}
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.
JS
on_completed: function (payment) {
    // Do stuff with payment object
}
on_completed: function (payment) {
    // Do stuff with payment object
}
﻿
Using a Promise:
JS
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_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.
JS
on_failure: function (error) {
    // Handle error
}
on_failure: function (error) {
    // Handle error
}
﻿
On Redirect (optional)
When the form finishes its work and is about to redirect the user, you can
intercept this action and handle redirection manually. Here is an example:
JS
on_redirect: function (url) {
    // Handle redirection manually
}
on_redirect: function (url) {
    // Handle redirection manually
}
﻿
Tokenize (Save) Credit Card (optional)
This option allows you to tokenize credit card information after successfully completing the transaction.
JS
credit_card: {
    save_card: "true",
}
credit_card: {
    save_card: "true",
}
﻿
Manual Payments (optional)
This option allows you to only authorize payments without capturing them. To capture the payment, you need to make an API call to the capture endpoint later on. Please review the API section for more details.
JS
credit_card: {
    manual: true,
}
credit_card: {
    manual: true,
}
﻿
Statement Descriptor
Allows the merchant to add a statement descriptor for the payment that will show in the card statement.
JS
{
  statement_descriptor: 'Merchant Name'
}
{
  statement_descriptor: 'Merchant Name'
}
﻿
Apple Pay Configurations (Required)
Only required if apple pay is enabled 
This is an object that contains Apple Pay specific configurations. Here is
an example:
JS
apple_pay: {
    // Apple Pay Configurations
}
apple_pay: {
    // Apple Pay Configurations
}
﻿
Version (optional)
This is used to specify the Apple Pay JS version. The default is 6. Here is an example:
JS
apple_pay: {
    version: 7
}
apple_pay: {
    version: 7
}
﻿
Country (required)
Apple Pay merchant country.
JS
apple_pay: {
    country: 'SA'
}
apple_pay: {
    country: 'SA'
}
﻿
Merchant Capabilities (optional)
Merchant capabilities to activate this Apple Pay session. Default is:
JS
apple_pay: {
    merchant_capabilities: [
        'supports3DS',
        'supportsCredit',
        'supportsDebit'
    ],
},
apple_pay: {
    merchant_capabilities: [
        'supports3DS',
        'supportsCredit',
        'supportsDebit'
    ],
},
﻿
Label (required)
Label to be displayed in the payment modal.
JS
apple_pay: {
    label: 'Ali Hardware Store'
}
apple_pay: {
    label: 'Ali Hardware Store'
}
﻿
Merchant Validation URL (required)
This URL is used to initiate the Apple Pay session. A POST request will be made
to the specified endpoint with a JSON object containing the URL. Here is the JSON
snippet:
JSON
{
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/paymentSession"
}
{
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/paymentSession"
}
﻿
The endpoint must return a response with the header Content-Type: application/json and
the session object obtained from Apple.
Here is the configuration example:
JS
apple_pay: {
    validate_merchant_url: 'https://mystore.test/applepay/validate-merchant'
}
apple_pay: {
    validate_merchant_url: 'https://mystore.test/applepay/validate-merchant'
}
﻿
In order to perform merchant validation, you need to register for an Apple Developer Account
and sign up for the Apple Developer program.
Now you must use the provided URL to perform the merchant validation﻿
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.
JS
apple_pay: {
    supported_countries: ['SA', 'US']
}
apple_pay: {
    supported_countries: ['SA', 'US']
}
﻿
Advanced Integration
If the form does not satisfy your needs, you can always build your own integration solution, and try our manual integration﻿.
Updated 23 Nov 2023
Did this page help you?
Payment Errors
Translations