Custom Payments
Credit Cards

24min
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 straightforward integration we recommend. that you 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.
Before Starting
Before you start the integration process, make sure you complete these steps:
Sign up for a Moyasar test account at Moyasar's Dashboard.﻿
﻿Get your API Key To authenticate your API request.
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 are required to authenticate the payment request and provide the 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
HTML
<form accept-charset="UTF-8" action="https://api.moyasar.com/v1/payments.html" method="POST">
  <button type="submit">Pay</button>
</form>
<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.
Add input of type hidden
Set the input’s name to callback_url
Set the value to the URL you want to redirect users to.
HTML
<input type="hidden" name="callback_url" value="https://www.my-store.com/payments_redirect" />
<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.
Add an input of type hidden
Set the input’s name to publishable_api_key
Set the value to your publishable API key
HTML
<input type="hidden" name="publishable_api_key" value="your_publishable_api_key_here" />
<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.
Add an input of type hidden
Set the input’s name to the amount
Set the value to the amount that you need to charge.
HTML
<input type="hidden" name="amount" value="1000" />
<input type="hidden" name="amount" value="1000" />
﻿
currency [optional]
The currency is optional and defaults to SAR.
Add an input of type hidden
Set the input’s name to currency
Set the value to the amount that you need to charge.
HTML
<input type="hidden" name="currency" value="SAR" />
<input type="hidden" name="currency" 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.
Add input of type hidden
Set the input’s name to source[type]
Set the value to the type of payment method
HTML
<input type="hidden" name="source[type]" value="creditcard" />
<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.
Add input of type hidden
Set the input’s name to description
Set the value of the description
HTML
<input type="hidden" name="description" value="Order id 1234 by guest" />
<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 the card’s holder name.
source[number] for the card’s number.
source[month] for the card's expiry month.
source[year] for the card's expiry year.
source[cvc] for the card's CVC.
﻿
Final code
HTML
<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>
<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 to 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 the 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
JS
// 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;
    });
});
// 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 errors section in our 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
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
﻿
Fetch the payment using its ID through the API, and verify its status, amount, and currency before accepting or placing any user's purchase or, using the ID we have saved in the Javascript example, perform the same verifications.
Updated 15 Aug 2024
Did this page help you?
Apple Pay Testing
STC Pay