Guides

About Embedded Fields

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

Suggest Edits

Embedded fields is a method for adding payment fields to your website or application. Use it to collect and process payment information on Maast servers while your customer remains on your site or application, seeing your branding. This method lets you reduce your PCI DSS compliance scope by using Maast's PCI DSS Level 1 certified platform.

This page provides an overview of embedded fields and the features it supports. The Quick Start guide gives instructions for a fast embedded fields setup with default settings. The remaining guides show you how to integrate Payments and Google Pay™ using embedded fields. See Aggregated Payments to use embedded fields for aggregated purchases. Embedded Fields Conventions provides further information applicable to embedded fields.

Features

The embedded fields method has the following benefits:

  • Flexible - Use one-time or permanent tokens for any request our Payment Gateway API supports.
  • Fully customized - Maintain your branding and complete control over placement of the embedded fields.
  • Under control - Configure security levels of Google V3 reCAPTCHA challenges in Maast Manager.
  • Secure - All cardholder data is collected and processed by Maast, a PCI DSS certified Level 1 compliant Service Provider.

This method supports the following transaction types:

  • Sale - Authorizes and captures payment in a single message.
  • Authorization - Sends cardholder data to the issuing bank for approval.
  • Tokenize - Saves credit card or ACH payment information to a token (card ID).
  • Verify - Sends cardholder data to the issuing bank for verification.
  • Capture - Captures an authorized transaction.
  • Void - Cancels an authorized transaction.
  • Credit - Issues a non-referenced credit or payment to a cardholder.
  • Refund - Issues a full or partial refund to a captured transaction.
  • Force - Forces a declined transaction into the system.
  • Batch Close - Immediately closes the open batch of transactions.

It supports these forms of payment:

  • Visa
  • Mastercard
  • Discover
  • American Express
  • Google Pay™
  • ACH

It supports the following payment types:

  • E-commerce
  • Card swipe
  • Recurring
  • Installment
  • Mail order
  • Telephone order

It supports these types of optional data:

  • Level II
  • Level III

How It Works

This section provides an overview of the payment flow process with embedded fields for one-time payments and then for repeat transactions that store a customer's payment information.

One-Time Payments

For one-time payments, the embedded fields payment flow is as follows:


Generate a transient key and load the form

  1. The customer selects to check out, and their browser makes a call to the merchant server.
  2. The merchant server authenticates and gets a transient key from the API.
  3. The merchant server uses the transient key and Maast's JavaScript library to generate embedded fields on the merchant's checkout page.

Verify the card and generate a card ID

  1. The customer fills the embedded field and selects to pay. The customer's browser submits the form, and the JavaScript library sends the cardholder data to Maast for verification.
  2. Maast completes verification with the card brands.
  3. If verification is positive, Maast generates a single-use token (card ID) and sends it to the customer's browser.

Authorize and complete payment

  1. The customer's browser sends the card ID to the merchant server and requests to complete the payment.
  2. The merchant server sends the information and a sale or authorization request to the API.
  3. Maast requests authorization from the card brands.
  4. Maast returns the response to the merchant server.
  5. If the payment is approved, the merchant server displays a receipt.

Repeat Payments

For repeat-customer payments, the embedded fields payment flow is as follows:


Generate a transient key and load the form

  1. The customer selects to check out, and their browser makes a call to the merchant server.
  2. The merchant server authenticates and gets a transient key from the API.
  3. The merchant server uses the transient key and Maast's JavaScript library to generate embedded fields on the merchant's checkout page.

Verify the card and generate a card ID

  1. The customer fills the embedded fields and selects to pay. The customer's browser submits the form and a request to tokenize, and the JavaScript library sends the cardholder data to Maast for verification.
  2. Maast completes verification with the card brands.
  3. If verification is positive, Maast generates a token (card ID) and sends it to the customer's browser.

Authorize and complete payment

  1. The customer's browser sends the card ID to the merchant server and requests to complete the payment.
  2. The merchant server sends the information and a sale or authorization request to the API.
  3. Maast requests authorization from the card brands.
  4. If the payment is approved, Maast stores the card ID, billing address, customer ID, and cardholder data.
  5. Maast returns the response, including the card ID and the first 6 and last 4 digits of the credit card number, to the merchant server.
  6. If the payment is approved, the merchant server displays a receipt.

CAPTCHA

We highly recommend that you use a CAPTCHA to prevent your site from being used to test cards. Maast can manage your reCAPTCHA inside the embedded fields frame, and you can edit its settings in Maast Manager.

Follow these steps to access reCAPTCHA settings for embedded fields:

  1. In your merchant sandbox account, select 'Administration' in the left-hand menu.
  2. Under 'Account Configuration,' select 'Settings.'
  3. Select the 'Embedded' tab at the top.

You can now see and edit the following reCAPTCHA settings:

  • Google V3 Recaptcha - Toggle this between 'Enabled' and 'Disabled.'
    • We recommend you enable this when your checkout page is not behind a login.
    • Disable this if you already display another CAPTCHA service.
    • See more about Google reCAPTCHA v3 here.
  • Threshold score - reCAPTCHA returns a score between 0.0 (very likely a bot) and 1.0 (very likely a good interaction). Type the threshold score below which requests should be marked as 'suspicious.'
  • Interval (min) - Type or use arrows to set the length of time (in minutes) to allow a certain number of 'suspicious' requests before resetting the counter.
  • Number of allowed suspicious requests - Type or use arrows to set the number of 'suspicious' requests to allow in the time interval set above.

Success Handler

A success handler function is required to load Maast embedded fields. The success handler is called after the card is successfully tokenized and a card_id is generated. The card information is passed as a parameter to the callback function as a JSON object. You can include the logic here to make payments from your servers using the card_id.

See Embedded Payments for a code sample of a success handler. See Embedded Fields Conventions for success response conventions and an example.


Error Handler

An onError callback function is optional. You can use it to handle errors. The error JSON object is passed as a parameter to the callback function.

See Embedded Payments for a code sample of an error handler. See Embedded Fields Conventions for error response conventions and an example.


Retries

Once the frame loads, the customer is allowed to retry a payment up to 5 times. After that, the customer is instructed to return to the previous step in your checkout process. When they do so, a new frame and transient key are generated. You can define your error handler so that it will receive an error object (with error code 99) when there are too many failed attempts. See Embedded Fields Conventions for a code sample of the error object.


Card Configuration

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. See sample card configuration code in Embedded Payments.

📘

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


ACH Configuration

By default, if you have configured your account to accept ACH payments, the embedded fields will show the tab to take ACH payments. You can use a JSON object to configure ACH payments in embedded fields. See sample ACH configuration code in Embedded Payments.


ACH Payments with Embedded Fields

This section provides recommendations and requirements for handling ACH payments with embedded fields.

ACH Consent Statement Requirement

If you add ACH payments to your website using Maast's embedded fields method, you must do the following:

  • Add a consent statement to your website.
  • Include a checkbox for your customer to indicate that they have read the statement and agree to the
    ACH payment.

See a sample consent statement on our ACH Conventions page.

ACH Validation Requirement

Maast has integrated with a NACHA-certified provider to verify first-use account information per the NACHA WEB Debit Account Validation Rule. Note the following:

  • Verification - Net-new requests to tokenize, verify, or transact with full ACH routing and account numbers collected via the internet will be sent for verification through our third-party provider.

  • Authorization codes - Any ACH sale request will return the response from the NACHA-approved third-party in the auth_code field of the payment gateway response. An auth_code will not appear for sales on accounts that are not net-new because the accounts have already been validated. Details of ACH auth_codes are available in the ACH Authorization Code Responses table.

  • Payment gateway response - After any request, the Payment Gateway API provides a description of the response in the rcode and rmsg fields. See the Payment Gateway API Response Codes table for responses to ACH transaction requests.

  • Failure response - Most issues with ACH payments are reported to you with the payment gateway response code (rcode) of 119, "Invalid ACH payment." See ACH Response Code 119 Detail Codes and Descriptions for more information.

Configuring Your Deposit Account for ACH Payments

If you are using a deposit account at a bank that is not Maast, please note the following:

  • You must ensure that your bank does not reject items due to account blocking and that it allows all potential debits and credits from the appropriate ACH payment identification numbers or company IDs.
  • Once Maast has approved you for ACH payments, contact your bank to request that it enable debits against your account for the following company IDs: 1113358832 and 1880394610.
  • A fee may be assessed if an attempt to debit your account fails due to missing company IDs.

Updated 12 months ago

What’s Next