Tokenization

Tokenization converts sensitive data into non-sensitive data (tokens). It allows businesses to securely store and transmit sensitive data while protecting user privacy. This guide explains tokenization, why you should use Moyasar, and how to get started.

How does tokenization work?

Tokenization is like having a locked safe for your customers sensitive information. When a customer makes a payment on your website, instead of storing their credit card information, you can use Moyasar's tokenization service to generate a random string of characters, called a token, to represent their sensitive data. The token is securely stored by Moyasar, and only the token is transmitted to your system.

Why use Moyasar's tokenization services?

Moyasar's tokenization service offers several benefits over traditional methods of handling sensitive data. For example:

Reduce the risk of data breaches and fraud.
Improve the user experience by eliminating the need to repeatedly enter sensitive data.
Save time and resources by automating the process of handling sensitive data.
Moyasar also has robust security measures in place to protect user data, including encryption, data backup, and compliance with industry standards. e.g.PCI DSS Level 1.

What types of cards can Moyasar tokenize?

Moyasar can be used to tokenize the following cards:

Mada
Visa
Mastercard

Before Starting

To start using Moyasar's tokenization services, follow these steps:

Register for an account with Moyasar.
Obtain the publishable API key from the settings page to access the tokenization services.
Contact our sales team at [email protected] to enable tokenization.

Configure Moyasar's Form

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://polyfill.io/v3/polyfill.min.js?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: 'Create Payment + Save Card',
    publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',
    callback_url: 'https://moyasar.com/thanks',
    methods: ['creditcard'],
  });
</script>

Step 3: Enable Tokenization

To enable tokenization, add the credit_card configuration option to your form, here is an example:

HTML
<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: 'Create Payment + Save Card',
    publishable_api_key: 'pk_test_AQpxBV31a29qhkhUYFYUFjhwllaDVrxSq5ydVNui',
    callback_url: 'https://moyasar.com/thanks',
    methods: ['creditcard'],
    credit_card: {
      save_card: true,
    },
  });
</script>

Resulting Form

The form uses our Payment APIs to perform required actions, you can learn more about it on Moyasar API Docs.

Learn more about available configuration keys here form configuration.

Step 4: Save Payment ID & Token

Save the payment ID and token 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 and the credit card token you can provide the on_completed configuration option with a URL, or a callback function. You will get a payment object containing the details of the payment, here is an example:

JSON
// Payment Object
{
  "id": "760878ec-d1d3-5f72-9056-191683faa872",
  "status": "initiated",
  "amount": 100,
  "fee": 0,
  "currency": "SAR",
  "refunded": 0,
  "refunded_at": null,
  "captured": 0,
  "captured_at": null,
  "voided_at": null,
  "description": "Create Payment + Save Card",
  "amount_format": "10.00 SAR",
  "fee_format": "0.00 SAR",
  "refunded_format": "0.00 SAR",
  "captured_format": "0.00 SAR",
  "invoice_id": null,
  "ip": "100.123.123.111",
  "callback_url": "https://moyasar.com/thanks",
  "created_at": "2023-03-13T16:05:23.490Z",
  "updated_at": "2023-03-13T16:05:23.490Z",
  "metadata": null,
  "source": {
    "type": "creditcard",
    "company": "visa",
    "name": "Mohammed ALI",
    "number": "XXXX-XXXX-XXXX-7606",
    "gateway_id": "moyasar_cc_12hJLGDRKMdnty7KpoksgBj",
    "reference_number": null,
    "token": "token_qbmmXzo97AESrZLS6KpWvof6uK2hAKcQGfEcKg",
    "message": null,
    "transaction_url": "https://api.moyasar.com/v1/transaction_auths/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/form?token=auth_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

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'],
  credit_card: {
    save_card: true,
  },
  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.

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'],
  credit_card: {
    save_card: true,
  },
  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();
      }
    });
  },
});

Best Practices For Using Tokenization Services

To ensure the security of your data when using tokenization services, follow these best practices:

Only store the tokenized data and avoid storing the original data.
Store the token in a safe location.

Resources

For more information about tokenization please see the documentation for Moyasar API tokenization.

How does tokenization work?​

Why use Moyasar's tokenization services?​

What types of cards can Moyasar tokenize?​

Before Starting​

Configure Moyasar's Form

Step 1: Include Moyasar's Scripts​

Step 2: Instantiating The Payment Form​

Step 3: Enable Tokenization​

Resulting Form​

Step 4: Save Payment ID & Token​

Option 1: URL​

Option 2: Callback Function​

Best Practices For Using Tokenization Services​

Resources​