Hosted fields reference

Use the following information as you work with hosted fields to create payment forms.

Exception API

The exception API provides a programmatic way to look at errors returned by the library.

Exception Format

Exceptions thrown by the API have error objects with a code, message, and an array of messages. The message will be a general reason for failure, with more specific errors contained in the messages array.

Parse an exception by calling:

const errorObject = window.AffiniPay.HostedFields.parseException(exception)

This will return you an error object like the one below

{
  code: 2
  message: "error missing tokenization data"
  messages: (1) ["CC token is invalid, credit card field must be defined and have a valid token"]
}

Exception Map

The exception map is used to look up exception types based on error codes thrown by the hosted fields API.

const exceptionMap = {
  1: 'initialization',
  2: 'configuration',
  3: 'network'
  4: 'payment'
}

Look up the exception type by calling exceptionMap with an error code:

const exceptionType = window.AffiniPay.HostedFields.exceptionMap[errorCode]

Schema Reference

Config Schema

{
  "type": "object",
  "additionalProperties": {},
  "properties": {
    "publicKey": {
      "type": "string"
    },
    “surchargeEnabled”: {
      “type”: “boolean”
    }
    "input": {
      "type": "object",
      "properties": {
        "css": {
          "type": "object",
          "additionalProperties": {},
          "properties": {
            ":focus": {
              "type": "object",
              "additionalProperties": {}
            },
            ":valid": {
              "type": "object",
              "additionalProperties": {}
            },
            ":invalid": {
              "type": "object",
              "additionalProperties": {}
            },
            ":required": {
              "type": "object",
              "additionalProperties": {}
            }
          }
        }
      }
    },
    "fields": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/FieldConfig"
      }
    }
  },
  "required": [
    "fields",
    "publicKey"
  ],
  "definitions": {
    "FieldConfig": {
      "type": "object",
      "additionalProperties": {},
      "properties": {
        "selector": {
          "type": "string"
        },
        "input": {
          "$ref": "#/definitions/FieldInput"
        }
      },
      "required": [
        "selector"
      ]
    },
    "FieldInput": {
      "type": "object",
      "properties": {
        "type": {
          "enum": [
            "credit_card_number",
            "cvv",
            "text"
          ],
          "type": "string"
        },
        "placeholder": {
          "type": "string"
        },
        "format": {
          "type": "boolean"
        },
        "css": {
          "type": "object",
          "additionalProperties": {},
          "properties": {
            ":focus": {
              "type": "object",
              "additionalProperties": {}
            },
            ":valid": {
              "type": "object",
              "additionalProperties": {}
            },
            ":invalid": {
              "type": "object",
              "additionalProperties": {}
            },
            ":required": {
              "type": "object",
              "additionalProperties": {}
            }
          }
        }
      },
      "required": [
        "type"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Field Config Schema

Each type of hosted field is set by the type key in the fieldConfig and has its own validation.

{
  "type": "object",
  "additionalProperties": {},
  "properties": {
    "selector": {
      "type": "string"
    },
    "input": {
      "$ref": "#/definitions/FieldInput"
    }
  },
  "required": [
    "selector"
  ],
  "definitions": {
    "FieldInput": {
      "type": "object",
      "properties": {
        "type": {
          "enum": [
            "credit_card_number",
            "cvv",
            "text"
          ],
          "type": "string"
        },
        "placeholder": {
          "type": "string"
        },
        "format": {
          "type": "boolean"
        },
        "css": {
          "type": "object",
          "additionalProperties": {},
          "properties": {
            ":focus": {
              "type": "object",
              "additionalProperties": {}
            },
            ":valid": {
              "type": "object",
              "additionalProperties": {}
            },
            ":invalid": {
              "type": "object",
              "additionalProperties": {}
            },
            ":required": {
              "type": "object",
              "additionalProperties": {}
            }
          }
        }
      },
      "required": [
        "type"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Form Data Schema

This is for credit card transactions only.

{
  "type": "object",
  "additionalProperties": {},
  "properties": {
    "exp_month": {
      "type": [
        "string",
        "number"
      ]
    },
    "exp_year": {
      "type": [
        "string",
        "number"
      ]
    }
  },
  "required": [
    "exp_month",
    "exp_year"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}