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

Field	Type	Description
`elementId`	string, required	Name of HTML id.
`type`	string, required	API attribute name that will be sent in the payload.
`placeholder`	string, required	What the user will see in the input field.
`validations`	string, optional	This 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`.
`autoComplete`	string, optional	This 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

Field	Type	Description
`environment`	string, required	`sandbox` for testing and `live` for live environments
`applicationId`	string, required	`Application` id that the payment card will be scoped to
`callback`	function, required	Callback 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

Field	Type	Description
`city`	string, optional	City (max 20 characters)
`country`	string, optional	3-Letter Country code
`email`	string, optional	Email address
`first_name`	string, optional	First name
`last_name`	string, optional	Last name
`line1`	string, optional	First line of the address (max 35 characters)
`line2`	string, optional	Second line of the address (max 35 characters)
`phone`	string, optional	Phone number
`postal_code`	string, optional	Zip or Postal code (max 7 characters)
`region`	string, optional	2-letter State code
`tags`	object, optional	Key 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

Field	Type	Description
`address`	object, required	Billing 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
`identity`	string, required	ID for the `Identity` resource which the account is to be associated
`name`	string, required	Full name of the registered card holder
`token`	string, required	ID for the `Token` that was returned via the tokenization client
`type`	string, required	Must pass TOKEN as the value

Address-object Request Arguments

Field	Type	Description
`city`	string, optional	City (max 20 characters)
`country`	string, optional	3-Letter Country code
`line1`	string, optional	First line of the address (max 35 characters)
`line2`	string, optional	Second line of the address (max 35 characters)
`postal_code`	string, required	Zip or Postal code (max 7 characters)
`region`	string, optional	2-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:

Making a Payment

Learn how to create a transfer and debit funds.

Creating and Capturing an Authorization

Learn how authorize funds on a card.