Embedded Fields Conventions

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.

FieldRequirementFormatDescription
formIDRequiredVariable lengthThe HTML ID of the submitted form.
modeOptionalString, default is testPossible values are test for the sandbox environment and prod for the production environment.
transientKeyRequiredFixed length, 32 ANThe transient key generated for use with embedded fields. The key expires in 12 hours. See Get Transient Key in API Reference for more information.
tokenizeOptionalBoolean, default is falseBy 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.
onSuccessRequiredJavaScript functionThe 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.
onErrorOptionalJavaScript functionThe 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.
preSubmitOptionalJavaScript functionA 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.
achConfigOptionalJSONIf 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.
cardConfigOptionalJSONBy 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.
formFieldsOptionalJSONBy default a CVV is optional on the embedded fields. This field to require it. See Embedded Payments for more information.
fontOptionalStringYou can use any font name listed on Google Fonts. Delimit with pipes () to use more than one font.
styleOptionalStringCSS 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:

FieldFormatDescription
enabledBooleanThe 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:

FieldFormatDescription
enabledBooleanThe default is true. Set this to false to hide ACH payments fields on the embedded payment form.
onPaymentTypeChangeJavaScript functionCard 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.

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

Success Response

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

FieldFormatDescription
card_idFixed length, 32 ANA 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_numberVariable length, up to 16 ANThe masked account number.
exp_dateFixed length, 4 N, in MMYY formatThe expiration date of the card number. Applicable only for credit cards.
card_typeVariable length, up to 2 ANThe card type. Refer to Card Types for a list of card types.
type_idFixed length, 1 ANBank 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.
codeVariable length, NStatus code from the hosted field submission. See the Response Codes table for possible values.
msgVariable length, ANA short description of the status. A possible value is Success.
detailJSON arrayA 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.

FieldFormatDescription
codeVariable length, NThe error code from the hosted field submission.
msgVariable length, ANThe error message, a short description of the error.
detailJSON arrayAn 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.