Guides

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 merchant 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 and return a card_id value to use as a token.

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

🚧

To use the embedded fields transient token, you must make it permanent by including tokenize set to true. Otherwise, the token will be single-use.


6. Configure Security

Configure your payment forms' reCAPTCHA security settings in the Maast merchant portal's 'Settings' page.


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 between "test" and "prod"
          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 and Go Live

See our Test and Go Live guide to test your embedded fields integration and to start transacting with an active production account.

📘

Change API and JavaScript

When moving to production with an embedded fields integration, don't forget to change both your API request and your JavaScript to production values.


Updated over 1 year ago