This page contains reference information specific to the embedded fields integration method. See the Embedded Fields section of this site for instructions and further information on the method.

Configuration Parameters

The table below shows the possible configuration parameters for embedded fields code. The embedded fields frame will not load if any required fields are not present.

Field	Requirement	Format	Description
`formID`	Required	Variable length	The HTML ID of the submitted form.
`mode`	Optional	String, default is `test`	Possible values are `test` for the sandbox environment and `prod` for the production environment.
`transientKey`	Required	Fixed length, 32 AN	The transient key generated for use with embedded fields. The key expires in 12 hours. See Get Transient Key in API Reference for more information.
`tokenize`	Optional	Boolean, default is `false`	By default, embedded fields generates a single-use `card_id` for Maast gateway requests. When `tokenize` is set to `true`, the `card_id` is stored and can be reused in future Maast gateway requests.
`onSuccess`	Required	JavaScript function	The success handler callback function to process the returned `card_id`. The function takes a JSON object argument that contains the `card_id` and number. See Embedded Payments for more information.
`onError`	Optional	JavaScript function	The error handler callback function to process errors from the embedded fields. The function takes a JSON object that contains information about the error. See Embedded Payments for more information.
`preSubmit`	Optional	JavaScript function	A callback JavaScript function that is invoked before Maast submits your form. If the function returns `false`, the form submission is canceled. The function can be used to disable elements in your form and prevent multiple submissions or to run JavaScript validations before the form is submitted.
`achConfig`	Optional	JSON	If you have enabled ACH payments, this JSON controls the display of an ACH tab on the embedded form. See the ACH Configuration Parameters table below. See ACH Configuration for more information.
`cardConfig`	Optional	JSON	By default all accounts can process card payments. Use this to hide card payment data on the embedded form. See the Card Configuration Parameters table below.
`formFields`	Optional	JSON	By default a CVV is optional on the embedded fields. This field to require it. See Embedded Payments for more information.
`font`	Optional	String	You can use any font name listed on Google Fonts. Delimit with pipes (`❘`) to use more than one font.
`style`	Optional	String	CSS rules can be passed to accomplish very general formatting. See the sample code in Embedded Payments.

Card Configuration Parameters

The structure of the cardConfig JSON object is as follows:

Field	Format	Description
`enabled`	Boolean	The default is `true`. Set this flag to `false` to hide card payment data on the embedded payment form.

ACH Configuration Parameters

The structure of the achConfig JSON object is as follows:

Field	Format	Description
`enabled`	Boolean	The default is `true`. Set this to `false` to hide ACH payments fields on the embedded payment form.
`onPaymentTypeChange`	JavaScript function	Card is the default payment type in embedded fields. Use this callback function to be notified when a customer changes the payment type to ACH.

Response Parameters

This section contains parameters and code samples of an embedded fields response.

Response Codes

See response codes for embedded fields requests below. Codes not listed below are reserved for internal or future use. Always check the detail array in the error object to get a description of the error.

`code`	Description
`0`	The request was successful.
`2`	The input validation failed. The detail array contains the list of error messages.
`12`	The request was rejected by the gateway.
`99`	There was a server problem processing the request.

Success Response

The table below shows the field conventions for an embedded fields success response.

Field	Format	Description
`card_id`	Fixed length, 32 AN	A single-use ID that can be used in a Maast payment gateway request to make a payment, authorization, verification, or tokenization. It is invalidated after 10 minutes or once it is used in a gateway request, whichever comes first. If the `tokenize` flag is set to `true` in the request, the `card_id` will not be single use; it will be stored for repeat use.
`card_number`	Variable length, up to 16 AN	The masked account number.
`exp_date`	Fixed length, 4 N, in MMYY format	The expiration date of the card number. Applicable only for credit cards.
`card_type`	Variable length, up to 2 AN	The card type. Refer to Card Types for a list of card types.
`type_id`	Fixed length, 1 AN	Bank account type. Applicable only for ACH payments. Possible values: • `C` - Personal checking account. • `S` - Personal savings account. • `K` - Business checking account. • `V` - Business savings account.
`code`	Variable length, N	Status code from the hosted field submission. See the Response Codes table for possible values.
`msg`	Variable length, AN	A short description of the status. A possible value is `Success`.
`detail`	JSON array	A detailed success message.

Sample code for an embedded fields success response is below:

{
  code: 0,
  msg: "Success",
  detail: ["Token request complete"],
  card_number: "411111xxxxxx1111",
  exp_date: “0423”,
  card_type: “VS”,
  card_id: "e7113e42158111e690fe0a728c0d49c0"
}

For approved transactions, the value of the code field is always 0. See About Embedded Fields for more information.

Error Response

The table below shows the conventions for an embedded fields error response.

Field	Format	Description
`code`	Variable length, N	The error code from the hosted field submission.
`msg`	Variable length, AN	The error message, a short description of the error.
`detail`	JSON array	An array of detailed error messages.

Below is sample code of an error response returned when the input validation has failed.

{
  code: 2,
  msg: "Validation Failed",
  detail: [
    "Card Number is required",
    "Expiry Date is required"
  ]
}

Below is sample code of an error response returned when the customer has retried a payment over 5 times without reloading the frame.

{
  code: 99,
  msg: "Internal Error",
  detail: [
    "Too many failed attempts. Please refresh your browser and start over."
  ]
}

See About Embedded Fields for more information.