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 aPaymentForm
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 thePaymentForm
library to the webpage that's hosting the form that collects payment details. To add the library, include the following the script: <script type="text/javascript" src="https://forms.finixpymnts.com/finix.js"></script>
Step 2: Initialize the Payment Form
Initialize thePaymentForm
library with:window.PaymentForm.card(function(state, binInformation)-> PaymentForm
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).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 aPaymentForm
object, you can customize and style it with your branding.attention
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.
|
autoComplete | string, optional | This allows the specified fields to auto-complete fields from saved card information. Available values include: |
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.
ThePaymentForm
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:
submit(environment, applicationID, callback)-> Form
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./*
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:
{
"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"
}
fraud_session_id
to detect and block potentially fraudulent payments. Add the following to your JavaScript to collect a fraud_session_id
. const FinixAuth = window.Finix.Auth('sandbox', 'MUeDVrf2ahuKc9Eg5TeZugvs');
fraud_session_id = FinixAuth.getSessionKey();
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 createdIdentity
.
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.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
{
"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"
}
}
}
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 aPayment Instrument
by making a POST
request to /payment_instrument
with the relevant token and the Identity#id
created for the buyer.warning
Payment Instrument
right away. Tokens that don't get connected within 30 mins of creation expire and can't be used.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:
{
"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"
}
}
}
card_type
. Available values for Payment Instruments
with type
PAYMENT_CARD include:- CREDIT
- DEBIT
- HSA_FSA
- NON_RELOADABLE_PREPAID
- RELOADABLE_PREPAID
- UNKNOWN
Identity
with a PUT request using the information saved in the Payment Instrument
.Next Steps
With thePayment Instrument
created, you can proceed with creating and capturing an Authorization
or creating a Transfer
: