Set up & Integrate
Learn how to set up and integrate Components.
Overview
We have created example implementations to help you get started with our Components products, which contains full code examples for better comprehension.
Server-side
Generate a session_id
session_id
The first step in the process is to use your API credentials to authenticate and login. A request can then be submitted to the /payment-sessions
endpoint containing the fields of the transaction
and tds
objects. Please view our API reference for further information on this endpoint.
Request:
{
"transaction": {
"order_id": "41142534-2e55-4eb2-9553-59784c73b2b0",
"amount": 15.02,
"currency": "gbp",
"capture": true
},
"tds": {
"is_active": true,
"challenge_preference": "no_preference",
"contact_url": "https://yourdomain.com/contact",
"redirect_url": "https://yourdomain.com/redirect",
"webhook_url": "https://yourdomain.com/webhook"
},
"payment_methods": [
"card",
"apple_pay",
"google_pay"
]
}
Note
When utilising the Payment component, you can pass the
payment_methods
array. This allows merchants to specify which payment methods are displayed to the user.Please note, this can not be passed for the Form or Fields components.
As a result of a successful response, we will return a session_id
. When a payment is then completed using Components, the parameters set within the session_id
will be used to complete the payment. Session IDs are temporary and will expire after 10 minutes. After this time, a new session_id
will need to be generated.
Successful response:
{
"session_id": "6d07e15a-b8ab-41e9-993b-39fbe688da92"
}
If a request is submitted to the /payment-sessions
endpoint and a required parameter is not present, we will return a 400 error.
Example response:
{
"status": "error",
"error_type": "validation",
"title": "Your request parameters did not pass our validation.",
"instance": "/v1/payment-sessions",
"invalid_parameters": [
{
"parameter": "transaction.order_id",
"reason": "transaction.order_id can not be empty"
}
]
}
Updating a session_id
session_id
There will be instances where the initially entered amount undergoes alterations from the original request. This could occur for many reasons, including, when there is an increased delivery charge or the cardholder applies a coupon code.
In such cases, initiate a PUT request to the endpoint /payment-sessions/{session_id}
, incorporating the modified parameters. This allows changes to be submitted to any of the supported parameters. Following a successful response, when the payment is completed within Components, the authorisation request will use the latest parameter set against the session_id
. Please refer to the API reference for further details.
Client side
Add Acquired.js within your code base
You can then include Acquired.js within the script tag. At this point we recommend performing an integrity check to confirm that the code has not been altered with.
Example:
<script type=”text/javascript” src=”https://cdn.acquired.com/sdk/v1/acquired.js” integrity=JS_INTEGRITY_HASH” crossorigin=”anonymous”></script>
If you are utilising Content Security Policy, we advise adding the cdn.acquired.com
domain to your whitelist. This ensures that the script can be loaded and executed on your web pages without triggering CSP violations.
Initialise the Acquired object
To initialise the Acquired object within the code base, you firstly need your public_key
value. This can be found in Settings > API Access.
Note
Ensure that you do not copy your
app_key
orapp_id
values as these are private and must never be exposed on the Client-Side.
You can also determine which environment is being targeted by inputting test
or production
within the options
.
Example:
const sessionId = “7048422b-6985-4608-9240-3dc9cc966317”;
const acquired = new Acquired(‘pkc4ac45debfe91b36e4fb092d2b30f3a5’);
const options = {
session: sessionId,
environment: “test”
};
const components = acquired.components(options);
Creating your Components
Once you have successfully initialised the Acquired.js object within your script, the next step is to choose the right component form for your business. Acquired provides three solutions for achieving this:
- Form: Use a single form to implement the Components solution.
- Payment: A payment form that allows for a quicker and more efficient checkout process by displayed pre-stored card options for returning customers.
- Fields: Utilise individual components to construct a solution that aligns with your requirements.
Note
You can still utilise Apple Pay and Google Pay through the Individual form, by a direct integration. Please refer to our Apple Pay and Google Pay guides for further information.
Option one: Form
Acquired's form solution consolidates all necessary components into a single form, facilitating streamlined checkout construction.
The HTML code represents the Acquired js DOM, representing the structure of the webpage. It includes each form element and the components contained within the div.
Example:
<form id=”card-form” class=”form-main”>
<div id=”payment-component”></div>
With our form solution, you can create the component, which contains all the required card fields, and then mount it in your checkout.
Example:
const paymentComponent = components.create(‘cardForm’, {
style: style
}),
paymentComponent.mount(‘#payment-component’);
Note
We have also built the ability to save cards for the Form integration, please refer to our Returning Customers guide for more information.
Option two: Payment
The payment component incorporates the functionality of storing card details. When a returning customer visits the merchant's website, the payment form will display a list of previously saved cards that are associated with the customer_id
. If a previously stored card is selected as the payment method by the customer, they will only be prompted to enter the CVV value, creating a smoother checkout experience.
As well as using a previously stored card, the customer will also have the option to "+ Use a different card". If the customer selects to pay with a different card, the payment form utilises the same logic as the card form and only displays the form as a single component (rather than the Individual components solution). By default, the most recently created card will be displayed first.
If there are no previously stored cards against the customer, we will display the card form.
The payment form includes support for both Apple Pay and Google Pay payment methods. To activate these features, follow these steps:
- Apple Pay: Register your domains
- Google Pay: Register your Google Developer account.
For further details on these procedures, please consult our respective guides.
Note
The payment form adopts the identical error messaging format as the card form, mirroring the style showcased in the card form images.
The first step is to build your payment form, and confirm the components to be included within the <div>
.
<form id="payment-form" class="form-main">
<div id="payment-component">
Then you can create and mount the payment form.
const paymentComponent = components.create('payment', {
style: style
});
paymentComponent.mount('#payment-component');
Option three: Fields
Acquired’s fields solution allows you to create your own card form, defining the components that you want to display within your checkout.
Unlike the two previous forms discussed above, the payment-component
contains multiple individual fields that can be created and mounted.
Note
When utilising the Fields solution, you have the option to tokenise card details for future use. For more details, please consult our Returning Customers guide.
Firstly, confirm which fields you want to display in your payment form by inputting the required fields within your code.
Example (the input fields can be named according to your preference):
<form id=”individual-form” class=”form-main”>
<div id=”payment-component”>
<div class=”input-field” id=”card-holder-component”></div>
<p clas="component-error"></p>
<div class=”input-field” id=”card-number-component”></div>
<p clas="component-error"></p>
<div class=”input-field” id=”card-expire-date-component”></div>
<p clas="component-error"></p>
<div class=”input-field” id=”card-cvv-component”></div>
<p clas="component-error"></p>
</div>
The next step is to create the individual components and mount them into your checkout.
const cardNumberComponent = components.create('cardNumber', {
style: style
});
cardNumberComponent.mount('#card-number-component');
const cardholderNameComponent = components.create('cardholderName', {
style: style
});
cardholderNameComponent.mount('#cardholder-component');
const cardExpireDateComponent = components.create('cardExpireDate', {
style: style
});
cardExpireDateComponent.mount('#card-expire-date-component');
const cardCvvComponent = components.create('cardCvv', {
style: style
});
cardCvvComponent.mount('#card-cvv-component');
Components configuration
Component object - Acquired.js
A component
object points to an embeddable element within your checkout, such as the card form or card expiration date.
Option | Definition | Possible Values |
---|---|---|
components.create | This creates a component ready for it to be mounted. | cardForm cardNumber cardholderName cardExpireDate cardCvv payment |
components.mount | Once you have created each required component , the next step is to mount them by referencing the <div> where it will be attached. This adds the component to the DOM, making it visible within your checkout. | The possible values will include the input-fields that have been created. |
Set your confirmParameters
The confirmParams
constant, allows you to send additional information for the payment authorisation request after the session has been initiated. You can pass through further information such as customer, shipping and billing data to support AVS verification.
Note
If you want to change the transaction or 3DS parameters generated in the
/payment-sessions
request, you are required to submit a PUT request to/payment-sessions/{session_id}.
For a list of the parameters that can be passed, please refer to our /payments endpoint.
Example:
const confirmParams = {
customer: {
reference: "cfe19f01-6fe5-4c82-be05-0f66054efde1",
billing: {
address: {
line_1: "Flat 1",
line_2: "152 Aldgate Drive",
city: "London",
postcode: "E1 7RT",
country_code: "GB"
},
email: "[email protected]",
phone: {
country_code: "44",
number: "2039826580"
},
shipping: {
address_match: true
},
webhook_url: 'https://www.yourdomain.com/webhook'
}
}
Handling form submit
Your are required to attach an event listener to the form element, which will listen for a “submit” event. This occurs when the user clicks on the submit button. The response will then be returned when the payment request has been processed, which refers to the confirmParams
function.
form.addEventListener(‘submit’, async (event) => {
event.preventDefault();
const response = await acquired.confirmPayment({
components,
confirmParams: confirmParams,
})
Handling errors
To handle errors within Components, you need to confirm which responses will be rendered.
Response statuses
Status | Description |
---|---|
isSuccess | The payment has been successfully processed. |
isTdsPending | Awaiting authentication completion. (Once the response has been returned, the redirect_url , which is defined within the session_id will contain the 3DS outcome.) |
isError | The request was received, but an error has occurred. |
if(response.isTdsPending()){
Window.location.href = response.data.redirect_url;
}
if(response.isSuccess()){
const messageContainer = document.querySelector(‘#error-message);
messageContainer.textContent = JSON.stringify(response.data);
}
if(response.isError()){
acquired.showComponentErrorMessage('.component-error', response.data);
const messageContainer = document.querySelector('#error-message');
messageContainer.textContent = JSON.stringify(response.data);
Handling 3-D Secure as an iframe
If you prefer not to load the tds window as a redirect, you have the option to load it as an iframe popup instead.
In the response for tds, update your code as follows:
if(response.isTdsPending()){
this.components.iframe.style.height = "revert-layer";
this.components.iframe.src = response.data.redirect_url;
// window.location.href = response.data.redirect_url;
}
Handling errors: Form
When an error occurs in the initial field, an error message will be displayed. Subsequent errors will be shown once the displayed error has been resolved.
<textarea id="error-message" placeholder="error message" readonly="true"></textarea>
Handling errors: Fields
In cases where multiple errors occur across various fields, all these errors will be displayed underneath the field that they occur in.
<form id=payment-form class=”form-main>
<div class=”input-field” id=”card-holder-component”></div>
<p class=”component-error”></p>
<div class=”input-field” id=”card-number-component”></div>
<p class=”component-error”></p>
<div class=”input-field” id=”card-expiry-date-component”></div>
<p class=”component-error”></p>
<div class=”input-field” id=”card-cvv-component”></div>
<p class=”component-error”></p>
</div>
In order to display the error message and enable custom messaging for individual fields, you are required to add the following code. The blur
event will ensure the error message is displayed whenever the component loses focuses (is clicked away after being interacted with).
components.on('blur', (response) => {
acquired.showComponentErrorMessage('.component-error', response);
const messageContainer = document.querySelector('#error-message');
messageContainer.textContent = JSON.stringify(response);
})
The default error message can then be overwritten to display what you require. In the below example we have set the message to "Invalid request".
if(response.isError()){
response.data.message = "Invalid request";
acquired.showComponentErrorMessage('.component-error', response.data);
const messageContainer = document.querySelector('#error-message');
messageContainer.textContent = JSON.stringify(response);
}
Error messaging
Components has a comprehensive suite of default error messaging that will be displayed to the end user. You have the option to customise error messaging by overriding any of the default messages.
The structure of the error response is outlined below:
Field | Description | Example |
---|---|---|
status | The current status of the response. | error decline |
component | The component where the error occurred. | cardForm cardNumber cardholderName cardExpireDate cardCvv payment |
error_type | The type of error returned. | required incomplete invalid not_accepted |
message | A message containing more detail about the error. | Cardholder name required |
Cardholder name required
{
"status": "error",
"component": "cardholderName",
"error_type": "required",
"message": "Cardholder name required"
}
Card number required
{
"status": "error",
"component": "cardNumber",
"error_type": "required",
"message": "Card number required"
}
Incomplete card number
{
"status": "error",
"component": "cardNumber",
"error_type": "incomplete",
"message": "Incomplete card number"
}
Invalid card number
{
"status": "error",
"component": "cardNumber",
"error_type": "invalid",
"message": "Invalid card number"
}
Card number not accepted
{
"status": "error",
"component": "cardNumber",
"error_type": "not-accepted",
"message": "Card number not accepted"
}
Expiry date required
{
"status": "error",
"component": "cardExpiryDate",
"error_type": "required",
"message": "Expiry date required"
}
Card expired
{
"status": "error",
"component": "cardExpiryDate",
"error_type": "expired",
"message": "Card expired"
}
Invalid card expiry year
{
"status": "error",
"component": "cardExpiryDate",
"error_type": "invalid",
"message": "Invalid card expiry year"
}
CVV required
{
"status": "error",
"component": "cardCvv",
"error_type": "required",
"message": "CVV required"
}
Incomplete CVV
{
"status": "error",
"component": "cardCvv",
"error_type": "incomplete",
"message": "Incomplete CVV"
}
Webhook notifications
We will send a status_update
webhook to update your application of the status of the payment.
In order to send webhook notifications, you must add the webhook_url
parameter to the confirmParams component when the session_id
is generated.
confirmParams:
webhook_url: 'https:/www.yourdomain.com/webhook'
status_update
webhook:
{
"webhook_type": "status_update",
"webhook_id": "113eeb0e-483e-4fc5-b1b3-4de99e3a9a6f",
"webhook_body": {
"transaction_id": "10ef7f23-2f7b-46d8-af40-fc9846ff59bf",
"status": "success",
"timestamp": 32908394083,
"order_id": "6112dfb4-81de-460e-ad39-7037677d6148"
}
}
We will also send a card_new
webhook, when a card is successfully created following authorisation.
card_new
{
"webhook_type": "card_new",
"webhook_id": "d68a7a29-47ce-43ea-bad3-0e4a35c5f09c",
"timestamp": 1684254231,
"webhook_body": {
"transaction_id": "0e789cf6-7e7a-3c55-870c-e69325975134",
"status": "success",
"order_id": "J97C6572ddt223-952",
"card_id": "77e595b6-686b-724b-6340-6c8ee0123778"
}
}
For further information on webhooks, including the structure and validating the integrity of a webhook, please view our documentation.
Updated 9 days ago