TS
createVaultManager(): HeadlessVaultManager
HeadlessVaultManager, which can be used to:
- fetch a list of vaulted payment methods for the
customerIdattached to the client session - delete a vaulted payment method for the
customerIdattached to the client session - perform a payment using a vaulted payment method
- create an input to collect the CVV for a vaulted payment method
TS
// Headless Checkout initialisation
const headless = await Primer.createHeadless(clientToken, {
onAvailablePaymentMethodsLoad: () => {
// create your UI for displaying payment methods
},
container: "#checkout-container",
});
await headless.start();
// Headless Vault Manager initialisation
const vaultManager = headless.createVaultManager();
Returns
An instance ofHeadlessVaultManager.
Hide HeadlessVaultManager
Hide HeadlessVaultManager
Get a list of Throws an error if the call to retrieve the vaulted payment methods fails.
VaultedPaymentMethod for the customerId attached to the client session.
Build your own UI to display, manage and perform payments with them.The list of vaulted payment methods is not affected by the checkout builder’s conditions.
For example, if you configured the checkout builder to not show
Paypal with the current client session,
but Paypal was vaulted previously, fetchVaultedPaymentMethods will still return it.This issue will be addressed and resolved in an upcoming release.TS
// Initialise Headless Checkout ...
const vaultManager = headless.createVaultManager();
const vaultedPaymentMethods = await vaultManager.fetchVaultedPaymentMethods();
Show VaultedPaymentMethod
Show VaultedPaymentMethod
A temporary identifier for the vaulted payment method. You should use this id with deleteVaultedPaymentMethod, and startPaymentFlow.ℹ️ This id changes with each call to fetchVaultedPaymentMethods.
An identifier for the vaulted payment method that doesn’t change across calls to fetchVaultedPaymentMethods.
Data associated to the payment instrument. You can use this information to display the vaulted payment method in your UI.As an example, for a vaulted card, you will receive:
TS
{
"first6Digits": "411111",
"last4Digits": "1111",
"expirationMonth": "05",
"expirationYear": "2030",
"cardholderName": "Primer Test",
"network": "VISA",
"binData": {
"network": "VISA",
"issuerCountryCode": "US",
"issuerName": "TEST BANK, N.A.",
"regionalRestriction": "UNKNOWN",
"accountNumberType": "UNKNOWN",
"accountFundingType": "UNKNOWN",
"prepaidReloadableIndicator": "NOT_APPLICABLE",
"productUsageType": "UNKNOWN",
"productCode": "UNKNOWN",
"productName": "UNKNOWN"
},
"isNetworkTokenized": false
}
The type of the payment instrument associated to the vaulted payment method.Examples of possible values (new values could be added as we add new payment methods):
APPLE_PAYCARD_OFF_SESSION_PAYMENTGOOGLE_PAYKLARNA_CUSTOMER_TOKENOFF_SESSION_PAYMENTPAYMENT_CARDPAYPAL_BILLING_AGREEMENTPAYPAL_ORDER
The 3DS authentication data for the vaulted payment method.
User-provided description for the vaulted payment method.
Delete a vaulted payment method by id for the Throws an error if the id passed does not match any payment method previously retrieved by fetchVaultedPaymentMethods.Throws an error if the call to delete the vaulted payment method fails.
customerId attached to the client session.You can get the id from any instance of VaultedPaymentMethod returned by fetchVaultedPaymentMethods.TS
// Initialise Headless Checkout ...
const vaultManager = headless.createVaultManager();
const vaultedPaymentMethods = await vaultManager.fetchVaultedPaymentMethods();
// Delete the first vaulted payment method
try {
await vaultManager.deleteVaultedPaymentMethod(vaultedPaymentMethods[0]?.id);
} catch (error) {
// handle errors
}
Show VaultedPaymentMethod
Show VaultedPaymentMethod
A temporary identifier for the vaulted payment method. You should use this id with deleteVaultedPaymentMethod, and startPaymentFlow.ℹ️ This id changes with each call to fetchVaultedPaymentMethods.
An identifier for the vaulted payment method that doesn’t change across calls to fetchVaultedPaymentMethods.
Data associated to the payment instrument. You can use this information to display the vaulted payment method in your UI.As an example, for a vaulted card, you will receive:
TS
{
"first6Digits": "411111",
"last4Digits": "1111",
"expirationMonth": "05",
"expirationYear": "2030",
"cardholderName": "Primer Test",
"network": "VISA",
"binData": {
"network": "VISA",
"issuerCountryCode": "US",
"issuerName": "TEST BANK, N.A.",
"regionalRestriction": "UNKNOWN",
"accountNumberType": "UNKNOWN",
"accountFundingType": "UNKNOWN",
"prepaidReloadableIndicator": "NOT_APPLICABLE",
"productUsageType": "UNKNOWN",
"productCode": "UNKNOWN",
"productName": "UNKNOWN"
},
"isNetworkTokenized": false
}
The type of the payment instrument associated to the vaulted payment method.Examples of possible values (new values could be added as we add new payment methods):
APPLE_PAYCARD_OFF_SESSION_PAYMENTGOOGLE_PAYKLARNA_CUSTOMER_TOKENOFF_SESSION_PAYMENTPAYMENT_CARDPAYPAL_BILLING_AGREEMENTPAYPAL_ORDER
The 3DS authentication data for the vaulted payment method.
User-provided description for the vaulted payment method.
Starts the payment flow. You should pass as a parameter the Throws an error if the id passed does not match any payment method previously retrieved by fetchVaultedPaymentMethods.Throws an error if the
id of a VaultedPaymentMethod previously retrieved with fetchVaultedPaymentMethods.Upon a successful invocation of this function, the SDK will automatically trigger the standard payment callbacks.TS
// Initialise Headless Checkout ...
const vaultManager = headless.createVaultManager();
const vaultedPaymentMethods = await vaultManager.fetchVaultedPaymentMethods();
// Start the payment flow using the first vaulted payment method
try {
await vaultManager.startPaymentFlow(vaultedPaymentMethods[0]?.id);
} catch (error) {
// handle errors
}
paymentInstrumentType in the vaulted payment method passed in is not recognised.Show VaultedPaymentMethod
Show VaultedPaymentMethod
A temporary identifier for the vaulted payment method. You should use this id with deleteVaultedPaymentMethod, and startPaymentFlow.ℹ️ This id changes with each call to fetchVaultedPaymentMethods.
An identifier for the vaulted payment method that doesn’t change across calls to fetchVaultedPaymentMethods.
Data associated to the payment instrument. You can use this information to display the vaulted payment method in your UI.As an example, for a vaulted card, you will receive:
TS
{
"first6Digits": "411111",
"last4Digits": "1111",
"expirationMonth": "05",
"expirationYear": "2030",
"cardholderName": "Primer Test",
"network": "VISA",
"binData": {
"network": "VISA",
"issuerCountryCode": "US",
"issuerName": "TEST BANK, N.A.",
"regionalRestriction": "UNKNOWN",
"accountNumberType": "UNKNOWN",
"accountFundingType": "UNKNOWN",
"prepaidReloadableIndicator": "NOT_APPLICABLE",
"productUsageType": "UNKNOWN",
"productCode": "UNKNOWN",
"productName": "UNKNOWN"
},
"isNetworkTokenized": false
}
The type of the payment instrument associated to the vaulted payment method.Examples of possible values (new values could be added as we add new payment methods):
APPLE_PAYCARD_OFF_SESSION_PAYMENTGOOGLE_PAYKLARNA_CUSTOMER_TOKENOFF_SESSION_PAYMENTPAYMENT_CARDPAYPAL_BILLING_AGREEMENTPAYPAL_ORDER
The 3DS authentication data for the vaulted payment method.
User-provided description for the vaulted payment method.
Create a
CvvInput that can be used to safely pass the secure code associated to a vaulted card to Primer’s backend.For security reasons, the input is rendered in an iframe on Primer’s domain and you won’t be able to access programmatically the value stored in the input.TS
const vaultManager = headless.createVaultManager();
// ... retrieve payment methods with fetchVaultedPaymentMethods
const cvvInput = await vaultManager.createCvvInput({
cardNetwork: vaultedPaymentMethod.paymentInstrumentData.network,
container: "#foo",
name: "cvv",
style,
placeholder: "123",
});
// Somewhere else in your code, create a `submitButton` to start the payment
// and a `cvvError` container to show validation errors
submitButton.onclick = () => {
// use metadata to show error messages
cvvError.innerText = cvvInput.metadata.error ?? "";
// don't start the payment flow if the `CVVInput` is in an invalid state
if (cvvInput.metadata.error) return;
try {
vaultManager.startPaymentFlow(vaultedPaymentMethod.id, {
cvv: cvvInput.valueToken,
});
} catch (error) {
// handle errors
}
};
Parameters:
Show CardSecurityCodeInputOptions
Show CardSecurityCodeInputOptions
A CSS selector that identifies the container where the
CvvInput will be appended. If the container is not found and the CVVInput cannot be mounted, the Promise returned by createCVVInput is resolved with null and an error message is logged to the developer’s console.The
aria-label attribute for the input element wrapped by CvvInput.The
id attribute that will be assigned to the HTMLIFrameElement used by CvvInput.An optional
name attribute for the input element wrapped by CvvInput.The name you provide will always be prefixed with cvv-, so if for example you pass name: 'custom' the CVVInput will wrap an HTMLInputElement that looks like this:TS
<input name="cvv-custom" /* Other attributes */ />
The
placeholder attribute for the input element wrapped by CvvInput.Whether to
append or prepend the CvvInput to its container.Additional attributes that can be applied to the
HTMLInputElement wrapped by CvvInput.Any attribute that would be valid on an <input> can be used here, however:nameis taken directly from theCardSecurityCodeInputOptionsoptionsmaxLengthandminLengthwill be inferred from thecardNetwork- type is always set to
telto provide a good UX when typing on a virtual keyboard - for security reasons event handlers such as
onkeydown,onkeyupwon’t be serialized and passed down to the input
data-*, aria-*…A CheckoutStyle object that will be applied to the input element.
The card network to determine the length of the field for CVV validation.You should pass the
paymentInstrumentData.network attribute on any of the VaultedPaymentMethods returned by fetchVaultedPaymentMethods.If you don’t pass a cardNetwork or the SDK cannot recognize the card network passed in, it will raise a warning and will default the validation of the CVV to a minimum length of 3 and a maximum length of 4.Returns:
Show CvvInput
Show CvvInput
The
valueToken representing the actual CVV value not accessible for security reasons.You can forward the token to HeadlessVaultManager.startPaymentFlow as the cvv parameter and under the hood it will be replaced with the value entered by the user.You can also access the valueToken and be informed of when it changes using addListener('change', listener).TS
// use `metadata` to check for validation errors
if (cvvInput.metadata.error) {
// display errors, don't start the payment flow
return;
}
try {
vaultManager.startPaymentFlow(vaultedPaymentMethod.id, {
cvv: cvvInput.valueToken,
});
} catch (error) {
// Handle startPaymentFlow errors
}
Add a listener for one of the supported events (
change, focus and blur) and return a function that can be called without arguments to remove the listener.focus and blur listeners do not receive any arguments.change listeners receive the following arguments:valueToken: a string representing the actual CVV value not accessible for security reasonsmetadata: additional details on the state of the input field wrapped by the CvvInput.
valueToken and metadata can be also accessed directly on an instance of CvvInput (cvvInput.valueToken, cvvInput.metadata)Alias of
addListener
Removes a listener previously added with
addListener. You should pass as parameters the exact same parameters passed to addListener.Alternatively, you can just use the function returned by addListener.Note: if you try to add a listener for an event that can’t be handled, addListener will not add it and it will return undefined instead of a function to remove it.Give focus to the
HTMLInputElement wrapped by CvvInput.Remove focus from the
HTMLInputElement wrapped by CvvInput.Removes the
CvvInput field from the DOM and detaches all event listeners previously added with addListener.A reference to the
HTMLIFrameElement wrapping the input.Additional details on the state of the input field wrapped by the
CvvInput.Show InputMetadata
Show InputMetadata
A label describing validation errors,
null if the input value has no validation errors.True if the input value has no validation errors.
True if the input is focused.
True if the input value is different from the initial.
True if the input has been touched once.
The
name attribute of the underlying HTMLInputElement field.Errors:
If thecontainer passed in the parameters is not found and the CVVInput cannot be mounted, the promise is resolved with null and an error message is logged to the developer’s console.Example:
Wrap aCvvInput in a React component using addListener('change', listener):TS
const CvvInput = ({ onChange }) => {
useEffect(() => {
const cvvInput = headless.createCvvInput({
cardNetwork: vaultedPaymentMethod.paymentInstrumentData.network,
container: "#foo",
name: "cvv",
style,
placeholder: "123",
});
cvvInput.addListener("change", onChange);
}, []);
return <div id="foo" />;
};
TS
const CardForm = () => {
const vaultManager = useVaultManager();
const selectedVaultedPaymentMethod = useSelectedVaultedPaymentMethod();
const [cvv, setCvv] = useState("");
return (
<div>
<CvvInput onChange={(value) => setCvv(value)} />
<SubmitButton
onClick={() =>
vaultManager.startPaymentFlow(vaultedPaymentMethod.id, { cvv })
}
/>
</div>
);
};
Throws
- Throws an error if a
customer.customerIdis not provided in the client session - Throws an error if the Headless Instance was not started