Payments

Credit Card

16min

Introduction
Overview
This section explains how to start accepting Mada, Visa, Mastercard, and American Express payments on your website using Moyasar's payment form.
Before Starting
Before you start accepting credit/debit card payments, make sure you complete these steps first:
Sign up for a Moyasar account on our dashboard.﻿
﻿Get your publishable API key to authenticate your form payment requests.
﻿
Setting Up Moyasar's Form
Moyasar Form is a lightweight Javascript library, that can get you up and running pretty quickly.
Step 1: Include Moyasar's Scripts
The current up-to-date version of the library is 1.14.0 which can be used through the official Moyasar CDN server:
https://cdn.moyasar.com/mpf/1.14.0/moyasar.js
https://cdn.moyasar.com/mpf/1.14.0/moyasar.css
You can start the integration by including the previous URLs in the head section of your website as follows:
HTML
<head>
  <!-- Other Tags -->

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

  <!-- Moyasar Scripts -->
  <script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?version=4.8.0&features=fetch"></script>
  <script src="https://cdn.moyasar.com/mpf/1.14.0/moyasar.js"></script>

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

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

  <!-- Moyasar Scripts -->
  <script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?version=4.8.0&features=fetch"></script>
  <script src="https://cdn.moyasar.com/mpf/1.14.0/moyasar.js"></script>

  <!-- Download CSS and JS files in case you want to test it locally, but use CDN in production -->
</head>
﻿
Step 2: Instantiating 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 our global Moyasar class.
HTML
<div class="mysr-form"></div>
<script>
  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>
<div class="mysr-form"></div>
<script>
  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
Field
Description
amount
Amount intended to be collected by this payment. A positive integer represents how much to charge in the smallest currency unit (e.g., 100 Halala to charge 1.00 SAR or 100 to charge ¥100, a zero-decimal currency). The minimum amount is 1 SAR or equivalent in charge currency. 
currency
3-letter ISO code for currency. E.g., SAR, CAD.
description
An arbitrary string that you can attach to a payment object. Payment description is only for your reference and it is NOT displayed to users.
publishable_api_key
Your publishable API key, learn more on how to get the key here.﻿
callback_url
URL of your website page to be redirected to after the customer completes a transaction. (e.g., https://example.com/orders).
supported_networks
This optional configuration option is used to set accepted card networks, in the form. The default value is all networks except amex.
methods
This is used to enable and disable payment methods on the form. By default, all the methods are enabled(creditcard, applepay, stcpay). 
Learn more about available configuration keys here form configuration.﻿
. Resulting Form
﻿
The form uses our Payment APIs to perform required actions, you can learn more about it on Moyasar API Docs.﻿
﻿
. Payment Lifecycle
The user clicks on the pay button.
Payment details are sent securely to Moyasar servers and then processed.
The user is then redirected to the 3-D Secure page for validation.
The user is redirected back to the URL specified in callback_url when the payment succeeds or fails﻿
﻿
Step 3: Save The 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',
})
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.
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.
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: function (payment) {
    return new Promise(function (resolve, reject) {
        // savePayment is just an example, your usage may vary.
        if (savePayment(payment)) {
            resolve({});
        } else {
            reject();
        }
    });
  },
})
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: function (payment) {
    return new Promise(function (resolve, reject) {
        // savePayment is just an example, your usage may vary.
        if (savePayment(payment)) {
            resolve({});
        } else {
            reject();
        }
    });
  },
})
﻿
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:
Return URL
https://www.my-store.com/payments_redirect?id=79cced57-9deb-4c4b-8f48-59c124f79688&status=paid&message=Succeeded
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
sequenceDiagram
 participant C as Cardholder
 participant S as Store
 participant M as Moyasar
 participant I as Issuing Bank 
 participant A as Accuring Bank
 
 C ->> M: POST v1/payments {"amount": "100", "source[type]"="creditcard", "source[number]"="4111...",...}
 
 M ->> I: Request bank 3D secure challenge
 
 I -->> M: Returns 3D secure challenge URL
 
 M -->> C: Redirect cardholder to 3D secure challenge URL
 
 C ->> I: Accept's challenge
 
 I -->> M: Returns Authorization response
 
 M ->> A: Requests to capture the amount
 
 A -->> M: Returns capture result
 
 M -->> C: Redirect to URL in callback_url store.com/thanks?id=d2i1...
 
 C ->> S: Requests to view the page
 
 S ->> M: GET v1/payments/d2i1... to verify payment
 
 M -->> S: {"id":"d2i1...", "amount":"100", ....} 
 
 S -->>C: Show page to cardholder 
 

 
 
sequenceDiagram
 participant C as Cardholder
 participant S as Store
 participant M as Moyasar
 participant I as Issuing Bank 
 participant A as Accuring Bank
 
 C ->> M: POST v1/payments {"amount": "100", "source[type]"="creditcard", "source[number]"="4111...",...}
 
 M ->> I: Request bank 3D secure challenge
 
 I -->> M: Returns 3D secure challenge URL
 
 M -->> C: Redirect cardholder to 3D secure challenge URL
 
 C ->> I: Accept's challenge
 
 I -->> M: Returns Authorization response
 
 M ->> A: Requests to capture the amount
 
 A -->> M: Returns capture result
 
 M -->> C: Redirect to URL in callback_url store.com/thanks?id=d2i1...
 
 C ->> S: Requests to view the page
 
 S ->> M: GET v1/payments/d2i1... to verify payment
 
 M -->> S: {"id":"d2i1...", "amount":"100", ....} 
 
 S -->>C: Show page to cardholder 
 

 
 
﻿
﻿

Field	Description
amount	Amount intended to be collected by this payment. A positive integer represents how much to charge in the smallest currency unit (e.g., 100 Halala to charge 1.00 SAR or 100 to charge ¥100, a zero-decimal currency). The minimum amount is 1 SAR or equivalent in charge currency.
currency	3-letter ISO code for currency. E.g., SAR, CAD.
description	An arbitrary string that you can attach to a payment object. Payment description is only for your reference and it is NOT displayed to users.
publishable_api_key	Your publishable API key, learn more on how to get the key here.
callback_url	URL of your website page to be redirected to after the customer completes a transaction. (e.g., https://example.com/orders).
supported_networks	This optional configuration option is used to set accepted card networks, in the form. The default value is all networks except amex.
methods	This is used to enable and disable payment methods on the form. By default, all the methods are enabled(creditcard, applepay, stcpay).

Updated 22 Aug 2024

Did this page help you?

Moyasar Documentation

Apple Pay