Embedded Fields

Finix Embedded Fields are available to securely collect the the details of a card payment.


info

At this time we don't plan on making further enhancements to our embedded fields. We encourage you to use our Tokenization Forms. For more information see Tokenization Forms.

To pass off the burden of complying with Payment Card Industry Data Security Standards (PCI DSS), use Finix Embedded Fields to collect and tokenize the payment details of buyers.

Library

Embedded Fields use a PaymentForm JavaScript library that lets you secure sensitive card and bank account data. Having buyers input their data into an embedded field prevents third parties from accessing the information that gets submitted.

Once the fields are initialized the library communicates the state of the fields through a JavaScript callback. The state object includes information validating the payment details submitted by the buyer.

See the following for examples on how to use our JavaScript library to tokenize payment details:

Step 1: Include Library and Desired HTML Elements

First we'll need to add the PaymentForm library to the webpage that's hosting the form that collects payment details. To add the library, include the following the script:
Copy
Copied
 <script type="text/javascript" src="https://forms.finixpymnts.com/finix.js"></script>

Step 2: Initialize the Payment Form

Initialize the PaymentForm library with:
Copy
Copied
window.PaymentForm.card(function(state, binInformation)-> PaymentForm
Next, configure the library to accept cards. This card method is the single entry point into the library. It initializes and returns a PaymentForm object that contains the embedded fields (i.e. name, number, expiration date, and CVV).
Copy
Copied
const paymentForm = window.PaymentForm.card(function(state, binInformation){
     // Logic for interacting with form's potential states (see jsFiddle for  example)
});

Step 3: Define Input Fields and Configure Styling

Now that you have a PaymentForm object, you can customize and style it with your branding.
attention
Requesting an address in your PaymentForm can lower interchange on credit card transactions.

Define Field Arguments

FieldTypeDescription
elementIdstring, requiredName of HTML id.
typestring, requiredAPI attribute name that will be sent in the payload.
placeholderstring, requiredWhat the user will see in the input field.
validationsstring, optionalThis allows customers to make a field required. The possible values are required, cardExpiry, cardNumber, and cardCVC. Each of the possible values returns a different error message when the required field is not present.
  • required returns Value is required.
  • cardExpiry returns Invalid expiration date.
  • cardNumber returns Invalid card number.
  • cardCVC returns Invalid CVV.
autoCompletestring, optionalThis allows the specified fields to auto-complete fields from saved card information. Available values include:
  • cc-number
  • cc-name
  • cc-exp
  • cc-csc
  • address-line1
  • address-line2
  • address-level1
  • postal-code
  • address-level2
  • Copy
    Copied
    function defineField(elementId, type, placeholder, validations, autoComplete) {
     // call field method with desired css styling
     const f = form.field(type, {
            validations,
            placeholder: { text: placeholder, hideOnFocus: true },
            autoComplete,
            styles: {
              default: {
                color: "black",
              },
              success: {
                color: '#5cb85c',
              },
              error: {
                color: '#d9534f',
              },
            }
          });
      // appends each field wrapper (that contains placeholder and styles) to the appropriate div
      document.getElementById(elementId).appendChild(f);
    }
    
    defineField("field-wrapper-number", "number", '4111 1111 1111 1111');
    defineField("field-wrapper-name", "name", 'Bo Jackson');
    defineField("field-wrapper-expiration_date", "expiration_date", '02/2020');
    defineField("field-wrapper-security_code", "security_code", '411');

    Step 4: Submit Payload and Handle Response

    We'll also need to configure what happens when the buyer submits the form.

    The PaymentForm needs to to register a click event that fires when the buyer submits the form and define a callback for handling the response.

    Use the following to submit the form when completed by the buyer:

    Copy
    Copied
    submit(environment, applicationID, callback)-> Form
    Next, configure the library to your specific Application where all of the form fields will be submitted during the executed POST request. We'll also want to register a click event that fires when our buyers submit the form and define a callback for handling the response.Once you've handled the response, store the ID to utilize the token in the future. To do this you will need to send the token ID from your front-end client to your back-end server.
    Copy
    Copied
    /*
    Form#submit(environment, applicationID, callback)-> Form
    */
    
    function submitForm() {
      // Sandbox or live for environment
      form.submit('sandbox', APgPDQrLD52TYvqazjHJJchM, function(err, res) {
        if (err) {
          console.log("There was an error");
        }
        // For illustrative purposes, we insert the JSON into the html.
        document.getElementById('preview').innerHTML = JSON.stringify(res, null, '  ');
      })
    }
    
    document.getElementById('button').addEventListener('click', function (e){
      e.preventDefault();
      submitForm();
    })
    
    // If user types "enter" instead of clicking submit button
    form.onSubmit(submitForm);

    Example Response:

    Copy
    Copied
    {
      "status": 201,
      "data": {
        "id": "TKghUufLdh4QQ96CBi928HP3",
        "fingerprint": "FPRiCenDk2SoRng7WjQTr7RJY",
        "created_at": "2022-07-22T02:39:45.87Z",
        "updated_at": "2022-07-22T02:39:45.87Z",
        "instrument_type": "PAYMENT_CARD",
        "expires_at": "2022-07-23T02:39:45.87Z",
        "currency": "USD"
      }
    }
    {
      "cardBrand": "mastercard",
      "bin": "520082"
    }
    We recommend also collecting a fraud_session_id to detect and block potentially fraudulent payments. Add the following to your JavaScript to collect a fraud_session_id.
    Copy
    Copied
        const FinixAuth = window.Finix.Auth('sandbox', 'MUeDVrf2ahuKc9Eg5TeZugvs');
    		fraud_session_id = FinixAuth.getSessionKey();
    When you make a payment and send the token to your back-end server, include the fraud_session_id. With the fraud_session_id included, Finix can review the details of the transaction and block potential fraud. For more information, see Fraud Detection.

    Arguments

    FieldTypeDescription
    environmentstring, requiredsandbox for testing and live for live environments
    applicationIdstring, requiredApplication id that the payment card will be scoped to
    callbackfunction, requiredCallback that will be executed when the HTTPRequest is finished.

    Step 5: Create an Identity for the Buyer

    Before you can use the newly tokenized card or bank account, you'll need to:

    • Create an Identity for the buyer.
    • Create a Payment Instrument with the created Identity.
    You can create an Identity with minimal or no information. To avoid asking for the same info multiple times, you don't need to request any additional information from the buyer when creating an Identity.

    To create an Identity, make POST request with whatever details you've gathered (e.g. name, email, phone, etc.) or create an empty Identity by leaving the entity empty.
    Copy
    Copied
    curl https://finix.sandbox-payments-api.com/identities \
        -H "Content-Type: application/json" \
        -H 'Finix-Version: 2022-02-01' \
        -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
        -d '
            {
              "entity": {
              }
            }'

    HTTP Request

    POST https://finix.sandbox-payments-api.com/identities

    Request Arguments

    FieldTypeDescription
    citystring, optionalCity (max 20 characters)
    countrystring, optional3-Letter Country code
    emailstring, optionalEmail address
    first_namestring, optionalFirst name
    last_namestring, optionalLast name
    line1string, optionalFirst line of the address (max 35 characters)
    line2string, optionalSecond line of the address (max 35 characters)
    phonestring, optionalPhone number
    postal_codestring, optionalZip or Postal code (max 7 characters)
    regionstring, optional2-letter State code
    tagsobject, optionalKey value pair for annotating custom metadata (e.g. order numbers)

    Example Response

    Copy
    Copied
    {
      "id" : "ID4KUMjzTggPzmCbvRUryQpE",
      "created_at" : "2023-01-03T18:56:30.40Z",
      "updated_at" : "2023-01-03T18:56:30.40Z",
      "application" : "APgPDQrLD52TYvqazjHJJchM",
      "entity" : {
        "amex_mid" : null,
        "annual_card_volume" : 0,
        "business_address" : null,
        "business_name" : null,
        "business_phone" : null,
        "business_tax_id_provided" : false,
        "business_type" : null,
        "default_statement_descriptor" : null,
        "discover_mid" : null,
        "dob" : null,
        "doing_business_as" : null,
        "email" : null,
        "first_name" : null,
        "has_accepted_credit_cards_previously" : false,
        "incorporation_date" : null,
        "last_name" : null,
        "max_transaction_amount" : 0,
        "mcc" : null,
        "ownership_type" : null,
        "personal_address" : {
          "line1" : null,
          "line2" : null,
          "city" : null,
          "region" : null,
          "postal_code" : null,
          "country" : null
        },
        "phone" : null,
        "principal_percentage_ownership" : null,
        "short_business_name" : null,
        "tax_authority" : null,
        "tax_id_provided" : false,
        "title" : null,
        "url" : null
      },
      "tags" : { },
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/verifications"
        },
        "merchants" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/merchants"
        },
        "settlements" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/settlements"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/transfers"
        },
        "payment_instruments" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/payment_instruments"
        },
        "associated_identities" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/associated_identities"
        },
        "disputes" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/ID4KUMjzTggPzmCbvRUryQpE/disputes"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        }
      }
    }
    You can update this Identity at a later time with a PUT request that uses the information in the Payment Instrument you create with the token.

    Step 6: Create a Payment Instrument

    Create a Payment Instrument by making a POST request to /payment_instrument with the relevant token and the Identity#id created for the buyer.
    warning
    Tokens should be used to create a Payment Instrument right away. Tokens that don't get connected within 30 mins of creation expire and can't be used.
    Copy
    Copied
    curl https://finix.sandbox-payments-api.com/payment_instruments \
        -H "Content-Type: application/json" \
        -H 'Finix-Version: 2022-02-01' \
        -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
        -d '
            {
                "token": "TKghUufLdh4QQ96CBi928HP3",
                "type": "TOKEN",
                "identity": "ID4KUMjzTggPzmCbvRUryQpE"
            }'

    HTTP Request

    POST https://finix.sandbox-payments-api.com/payment_instruments

    Request Arguments

    FieldTypeDescription
    addressobject, requiredBilling address (Full description of child attributes below)
    Note: Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions
    identitystring, requiredID for the Identity resource which the account is to be associated
    namestring, requiredFull name of the registered card holder
    tokenstring, requiredID for the Token that was returned via the tokenization client
    typestring, requiredMust pass TOKEN as the value

    Address-object Request Arguments

    FieldTypeDescription
    citystring, optionalCity (max 20 characters)
    countrystring, optional3-Letter Country code
    line1string, optionalFirst line of the address (max 35 characters)
    line2string, optionalSecond line of the address (max 35 characters)
    postal_codestring, requiredZip or Postal code (max 7 characters)
    regionstring, optional2-letter State code

    Example Response:

    Copy
    Copied
    {
      "id" : "PImmCg3Po7oNi7jaZcXhfkEu",
      "created_at" : "2022-10-10T05:32:17.78Z",
      "updated_at" : "2022-10-10T05:35:04.55Z",
      "application" : "APgPDQrLD52TYvqazjHJJchM",
      "created_via" : "API",
      "currency" : "USD",
      "enabled" : true,
      "fingerprint" : "FPRiCenDk2SoRng7WjQTr7RJY",
      "identity" : "ID4KUMjzTggPzmCbvRUryQpE",
      "instrument_type" : "PAYMENT_CARD",
      "address" : {
        "line1" : "900 Metro Center Blv",
        "line2" : null,
        "city" : "San Francisco",
        "region" : "CA",
        "postal_code" : "94404",
        "country" : "USA"
      },
      "address_verification" : "POSTAL_CODE_AND_STREET_MATCH",
      "bin" : "520082",
      "brand" : "MASTERCARD",
      "card_type" : "DEBIT",
      "expiration_month" : 12,
      "expiration_year" : 2029,
      "issuer_country" : "NON_USA",
      "last_four" : "8210",
      "name" : "Amy White",
      "security_code_verification" : "MATCHED",
      "tags" : {
        "card_name" : "Business Card"
      },
      "type" : "PAYMENT_CARD",
      "_links" : {
        "self" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu"
        },
        "authorizations" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/authorizations"
        },
        "transfers" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/transfers"
        },
        "verifications" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/verifications"
        },
        "application" : {
          "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "identity" : {
          "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K"
        },
        "updates" : {
          "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/updates"
        }
      }
    }
    The type of card that gets saved is detailed in card_type. Available values for Payment Instruments with type PAYMENT_CARD include:
    • CREDIT
    • DEBIT
    • HSA_FSA
    • NON_RELOADABLE_PREPAID
    • RELOADABLE_PREPAID
    • UNKNOWN
    You can also update the buyer Identity with a PUT request using the information saved in the Payment Instrument.

    Next Steps

    With the Payment Instrument created, you can proceed with creating and capturing an Authorization or creating a Transfer: