Embedded Payments

Embed transaction fields in your application. Collect and process payment information on Maast servers.

Suggest Edits

This guide shows you how to process credit card or ACH payments using embedded fields. Follow the steps below to set up and configure embedded fields for payments.

Prerequisites

  1. See Create a Sandbox Account to sign up and log in to the Maast Manager portal.

  2. Follow the steps in Get Your API Credentials to save a sandbox ID and API key.

  3. See Authentication to format the credentials and generate your API token.

  4. Follow the Embedded Quick Start guide to get a transient key and embed a basic payment form on your site.

Integrate

Follow the steps below to add event handlers and configure your payment options:

1. Success Handler

Add a success handler to the <script> block as shown below. You can add your custom code to the onSuccess method to display an approval and redirect your customer as needed. The success handler is called whenever a transaction is approved by the gateway:

onSuccess: (data) => {
            const { card_id, card_number } = data;
            console.log(data);
            alert( "card id is "+ card_id +", card number is "+ card_number );
            // Make payment from server using the token
  					if(code = 0) then doSuccess();
          }

See About Embedded Fields for more information and Embedded Fields Conventions for an error response sample and parameters.


2. Error Handler

Add an error handler to the <script> block as shown below. You can add your custom code to the onError method to display necessary information and redirect your customer. The error handler is optional but recommended. It is called whenever a transaction is unsuccessful:

onError: (error) => {
            if( error.detail ) {
              for( let key in error.detail ) {
                console.log(error.detail[key]);
              }
            }
          },

See About Embedded Fields for more information and Embedded Fields Conventions for an error response sample and parameters.


3. Configure Payments

Add fields to the <script> block to configure the types of payments that you will accept.

By default, the embedded fields form displays fields for card payment data. You can use an optional JSON object to hide card payment data fields on embedded fields. To hide card payment data fields, set the value of the enabled field in the cardConfig object to false, as shown below:

cardConfig: {
            enabled: false,
          },

To accept ACH payments, set the value of enabled in the achConfig object to true and call onPaymentTypeChange, as shown below:

achConfig: {
            enabled: true,
            onPaymentTypeChange: function (data) {
              console.log("Display ", data);
            }

By default, if you have configured your account to accept ACH payments, the embedded fields will show the tab to take ACH payments. Set the enabled field to false if you do not wish to show this tab. See Embedded Fields Conventions for ACH for more information.

🚧

NOTE: If your account is set up to receive ACH payments, you must meet ACH consent statement and validation requirements. See ACH Conventions for more information.

📘

NOTE: If both card and ACH payments are disabled, the form will default to card payment.


4. Configure CVV2

If you wish to require the CVV2 field in your payment form, define the cvv2 function in formFields within the <script> block as below:

formFields: {
            cvv2: {
              required: true
            }
          }

Set this flag to false if you do not wish to require the CVV field.


5. Configure Tokenization

Add a flag in the <script> block to store payment information in the Card Vault.

  • By default, embedded fields generate a single-use card_id for each Maast gateway request.
  • To store the card_id in the Card Vault, set tokenize to true, as shown below. This generates a card ID that can then be reused in future Maast gateway requests:
tokenize: true,

6. Configure Security

Configure your payment forms' reCAPTCHA security settings in Maast Manager Settings.


Once configured, the code for your embedded payments field will resemble the following sample:

<!doctype html>
<head>
  <style>#qp-embedded-container { border: 1px solid black; }</style>
  <link rel="stylesheet" href="https://app.qualpay.com/hosted/embedded/css/qp-embedded.css">
</head>
<body>
  <script src="https://app.qualpay.com/hosted/embedded/js/qp-embedded-sdk.min.js"></script>

  <form id="my-payment-form" method="post" action="/">
    <div id="qp-embedded-container" align="center"></div>
    <script>
      qpEmbeddedForm.loadFrame(999000010003,                // merchant ID
        {
          formId: "my-payment-form",
          mode: "test",                                     // change mode
          transientKey: "e419296f786a11e793370a3416b2e023", // transient key
          tokenize: true,                                   // set to true to make card_id permanent
          onSuccess: (data) => {
            const { card_id, card_number } = data;
            console.log(data);
            alert( "card id is "+ card_id +", card number is "+ card_number );
            // Make payment from server using the token
          },
          onError: (error) => {
            if( error.detail ) {
              for( let key in error.detail ) {
                console.log(error.detail[key]);
              }
            }
          },
          cardConfig: {
            enabled: true,
          },
          achConfig: {
            enabled: true,
            onPaymentTypeChange: function (data) {
              console.log("Display ", data);
            },
          },
          formFields: {
            cvv2: {
              required: true
            }
          },
          font: 'Titillium Web',
          style:
            "#root { min-width: 260px; }" +
            ".content {" +
            "  background-color: #35F;" +
            "  font-family: 'Titillium Web';" +
            "}",
        });
    </script>
    <input type="submit" name="submit" value="Pay Now"></input>
  </form>
</body>
</html>

Test

Start testing now at https://app-test.maast.com.

Go Live

Follow these steps to start transacting with an active production account:

Updated 19 days ago