API GuideDashboard
Home
Payments
Automation
Observability
Reconciliation
Payment Methods
Fraud Providers
SDK Reference
Changelog
1234567891011
createPaymentMethodManager(  type: string): Promise<  | ICardPaymentMethodManager  | INativePaymentMethodManager  | IRedirectPaymentMethodManager  | IFormWithRedirectPaymentMethodManager  | IKlarnaPaymentMethodManager  | IAchPaymentMethodManager  | null>
ts
copy

There are five types of manager that can be returned by this function, depending on the type provided as first argument: Card, Native, Redirect, Form With Redirect, Klarna Payment Method and ACH.

In case the the type specified is not supported, the function will return null instead.

Card

1234
createPaymentMethodManager(    type: "PAYMENT_CARD",    options?: PaymentMethodManagerOptions): Promise<ICardPaymentMethodManager | null>
ts
copy

Create an instance of the ICardPaymentMethodManager, which can be used to manage credit card payments.

Parameters

type
"PAYMENT_CARD"
When it matches this type, a manager for card payment methods will be returned.
options
object

Options to configure the payment method manager.

Properties
onCardMetadataChange
(metadata: CardMetadata) => void

Called when the card metadata changes. Takes a CardMetadata object as its argument.

CardMetadata
type
CardNetwork | nullDeprecated

Deprecated: Use onCardNetworksChange instead

Allowed card networks for credit card payments, one of CardNetwork.

possibleTypes
CardNetwork[]Deprecated

Deprecated: Use onCardNetworksChange instead

An array of CardNetwork. Reduces to one or zero elements as more digits on the card number are input.

cvvLength
number
Usually 3 digits, but can sometimes be 4.
cardNumberLength
number
Represents the length of the card number for the given card type.
onCardNetworksChange
(event: CardNetworkChangeEvent) => void

Called when Headless Checkout detects new card networks from the card number entered by the user.

Makes available an event of type CardNetworkChangeEvent.

CardNetworkChangeEvent
detectedCardNetworks
CardNetworks

All the detected card networks, including the ones that are not allowed.

Use the following snippet to get the card network that should be presented to the user:

detectedCardNetworks.preferred ?? detectedCardNetworks.items[0]

CardNetworks
items
CardNetworkDetails[]

An array of the card networks.

CardNetworkDetails
allowed
boolean

Whether or not the card network is allowed, according to orderedAllowedCardNetworks passed in the Client Session.

displayName
string
A human readable name for the card network.
network
string
A value that represents the card network in Primer's systems.
preferred
CardNetworkDetails | undefined

The first allowed card network in items. In case no network is allowed, undefined.

CardNetworkDetails
allowed
boolean

Whether or not the card network is allowed, according to orderedAllowedCardNetworks passed in the Client Session.

displayName
string
A human readable name for the card network.
network
string
A value that represents the card network in Primer's systems.
selectableCardNetworks
CardNetworks | undefined

In case the card has zero or only one network that is allowed, undefined. Otherwise, all the allowed cards.

Use this to show the card networks the user can choose from in the case of a co-badged cards.

CardNetworks
items
CardNetworkDetails[]

An array of the card networks.

CardNetworkDetails
allowed
boolean

Whether or not the card network is allowed, according to orderedAllowedCardNetworks passed in the Client Session.

displayName
string
A human readable name for the card network.
network
string
A value that represents the card network in Primer's systems.
preferred
CardNetworkDetails | undefined

The first allowed card network in items. In case no network is allowed, undefined.

CardNetworkDetails
allowed
boolean

Whether or not the card network is allowed, according to orderedAllowedCardNetworks passed in the Client Session.

displayName
string
A human readable name for the card network.
network
string
A value that represents the card network in Primer's systems.
source
'REMOTE' | 'LOCAL' | 'LOCAL_FALLBACK'
The source of the information.
Values
LOCAL

This happens when less than 8 digits are entered in the cardnumber field.

Headless Checkout retrieved the card networks using static information bundled with the SDK. This information can only identify international cards.

REMOTE

This happens when 8 digits or more are entered in the cardnumber field.

Headless Checkout retrieved the card networks using Primer's BIN data.

LOCAL_FALLBACK

This happens when Headless Checkout fails to contact Primer's BIN data.

Falls back to the static information bundled with the SDK (see LOCAL).

onCardNetworksLoading
() => void

Called when card network information is being fetched from Primer's servers.
Will only trigger when event.source === 'REMOTE' in onCardNetworksChange.

Returns

Promise<ICardPaymentMethodManager | null>

A promise that resolves to an instance of ICardPaymentMethodManager or null.

ICardPaymentMethodManager
createHostedInputs
() => HostedInputs

Create an object with three hosted inputs: cardNumberInput, expiryInput, and cvvInput.

HostedInputs
cardNumberInput
IHeadlessHostedInput
The headless hosted input for the card number.

See HeadlessHostedInput.

expiryInput
IHeadlessHostedInput
The headless hosted input for the expiry date.

See HeadlessHostedInput.

cvvInput
IHeadlessHostedInput
The headless hosted input for the CVV.

See HeadlessHostedInput.

setCardholderName
(cardholderName: string) => void
Set the name of the cardholder.
removeHostedInputs
() => void
Remove the hosted inputs.
submit
() => Promise<void>
Create a payment method based on the current values after tokenization. Returns a Promise that resolves when the payment has been created.
validate
() => Promise<Validation>
Validate the state of the payment method. Returns a Promise that resolves with a Validation object.
Validation
valid
booleanRequired
Indicates whether the validation was successful or not.
validationErrors
InputValidationError[]Required

An array of objects containing information about any input validation errors that occurred during the validation process.

InputValidationError
name
stringRequired
The name of the input field that produced the error.
error
stringRequired

The type of error that occurred.

Possible values:

  • cardNameRequired: cardholder's name is not provided.
  • cardNameContainsNumbers: cardholder's name contains numbers.
  • cardNameLength: cardholder's name does not match the expected length (minimum: 2, maximum: 45 characters).
  • cardNameContainsInvalidCharacters: cardholder's name contains characters that are not supported (only Latin characters are allowed).
  • cardRequired: card number is not provided.
  • unsupportedCardType: provided card number does not match the allowed card networks.
  • cardIncomplete: provided card number does not match the expected length.
  • cardInvalid: provided card number is invalid. Additional details might be available in the message field.
  • cvvRequired: card's security code (CVV) is not provided.
  • cvvIncomplete: card's security code (CVV) does not match the expected length (minimum: 3 characters).
  • cvvInvalid3: card's security code (CVV) does not match the expected length (exact: 3 characters).
  • cvvInvalid4: card's security code (CVV) does not match the expected length (exact: 4 characters).
  • expiryRequired: card's expiry date is not provided.
  • cardExpired: card has expired.
  • expiryMonthInvalid: expiry date's month is invalid.
  • expiryYearInvalid: expiry date's year is invalid.
message
stringRequired
A human-readable message describing the error that occurred.
error
string
A string describing any error that occurred during the validation process.
reset
() => void
Reset the hosted fields to their initial state.

Native

123
createPaymentMethodManager(    type: "PAYPAL" | "GOOGLE_PAY" | "APPLE_PAY",): Promise<INativePaymentMethodManager | null>
ts
copy

Create an instance of the INativePaymentMethodManager, which can be used to manage native payment methods like PayPal, Google Pay, and Apple Pay.

Parameters

type
"PAYPAL" | "GOOGLE_PAY" | "APPLE_PAY"
The type of native payment method to manage.

Returns

Promise<INativePaymentMethodManager | null>

A promise that resolves to an instance of INativePaymentMethodManager or null. An interface for creating a native payment method button.

INativePaymentMethodManager
createButton
() => IHeadlessPaymentMethodButton

Create a native payment method button. Returns a HeadlessPaymentMethodButton.

Redirect

123
createPaymentMethodManager(    type: PaymentMethodType,): Promise<IRedirectPaymentMethodManager | null>
ts
copy

Create an instance of the IRedirectPaymentMethodManager, which can be used to manage redirect-based payment methods.

Parameters

type
PaymentMethodType

The type of redirect-based payment method to manage, one of PaymentMethodType (except ADYEN_IDEAL).

Returns

Promise<IRedirectPaymentMethodManager | null>

A promise that resolves to an instance of IRedirectPaymentMethodManager or null.

IRedirectPaymentMethodManager
start
() => Promise<void>
Start the redirect payment flow.
addEventListener
(event: EventTypes, callback: EventListener) => void
Add an event listener to the button.
EventTypes
"blur" | "change" | "click" | "close" | "error" | "focus"
EventListener
(event?: Event) => void

Form With Redirect

1234
createPaymentMethodManager(    type: "ADYEN_IDEAL",    options?: FormWithRedirectPaymentMethodManagerOptions): Promise<IFormWithRedirectPaymentMethodManager | null>;
ts
copy

Create an instance of the IFormWithRedirectPaymentMethodManager, which can be used to manage redirect-based payment methods which also require an extra form and user interaction.

Parameters

type
"ADYEN_IDEAL"
The type of form with redirect payment method to manage.
options
FormWithRedirectPaymentMethodManagerOptions

Options to set up the payment method.

Properties
onConfigurationLoad
(payload: ConfigurationPayload) => void

Called when the payment method configuration changes. The properties contained on the payload object depends on the payment method, for example, bankIssuers will be defined when the payment method is ADYEN_IDEAL.

ConfigurationPayload
error
PrimerClientError | undefined
Properties
code
ErrorCode
message
string
diagnosticsId
Nullable<string>
data
object
isFromDeveloper
boolean
bankIssuers
BankIssuer[] | undefined
Properties
id
string
name
string
iconUrl
string

Returns

Promise<IFormWithRedirectPaymentMethodManager | null>

A promise that resolves to an instance of IFormWithRedirectPaymentMethodManager or null.

IFormWithRedirectPaymentMethodManager
start
() => Promise<void>

Set up the payment method loading the configuration, which will be provided through the onConfigurationLoad callback.

submit
(payload: T) => Promise<InputValidationError>

Validates the submitted payload, if the submitted payload is invalid it returns the validation errors, otherwise, if the payload is valid, it will start the redirect payment flow.

The payload to be submitted type T depends on the payment method, an example of this type can be the BankIssuer for the ADYEN_IDEAL payment method:

payload
BankIssuer
Properties
id
string
name
string
iconUrl
string
addEventListener
(event: EventTypes, callback: EventListener) => void
Add an event listener to the button.
EventTypes
"blur" | "change" | "click" | "close" | "error" | "focus"
EventListener
(event?: Event) => void

Klarna

1234
createPaymentMethodManager(    type: "KLARNA",    options?: KlarnaPaymentMethodManagerOptions): Promise<IKlarnaPaymentMethodManager | null>
ts
copy

Create an instance of the IKlarnaPaymentMethodManager, which can be used to manage Klarna specific payment methods which also require an extra form and user interaction.

Parameters

type
"KLARNA"
The type of payment method to manage.
options
KlarnaPaymentMethodManagerOptions

Options to configure the payment method manager.

Properties
onPaymentMethodCategoriesChange
(paymentMethodCategories: KlarnaPaymentMethodCategory[]) => void
A callback that is called when the payment categories for Klarna have changed. Sends back an array with the values needed to render the payment categories for Klarna.
paymentMethodCategories
KlarnaPaymentMethodCategory[] | []
Properties
id
Represents the id of the payment method category
name
stringRepresents the name of the payment method category
descriptiveAssetUrl
stringRepresents the url of the asset that can be used to indicate a Klarna Payment
standardAssetUrl
stringRepresents the url of the asset that can be used to indicate a Klarna Payment

Returns

Promise<IKlarnaPaymentMethodManager | null>

A promise that resolves to an instance of IKlarnaPaymentMethodManager or null.

IKlarnaPaymentMethodManager
start
(paymentPayload: KlarnaPaymentPayload) => Promise<void>
This function starts the payment process. It should be called with the selected payment method category id, when the user has selected and confirmed the desired payment category. The payment method category id which needs to be sent to the start function can be retrieved from the onPaymentMethodCategoriesChange function
paymentPayload
{ paymentMethodCategoryId: string }
Properties
paymentMethodCategoryId
stringRepresents the id of the payment method category
renderCategory
(details: RenderCategoryDetails) => Promise<void>
This function is used so that Klarna can render the selected payment category details (paymentMethodCategoryId) in a DOM element (containerId). It uses a callback (onHeightChange) to inform when the height of the contianer has changed.
details
{ containerId: string, paymentMethodCategoryId: string, onHeightChange:(newHeight:number)=> void }
Properties
containerId
stringThe container id of a DOM element in which the payment methods category details will be displayed
paymentMethodCategoryId
stringThe id of the payment method category selected i.e. 'pay_later', 'pay_now', 'pay_over_time'
onHeightChange
(height: number) => voidThe callback used to retrieve thew new height of the selected payment method categoy
height
numberRepresents the new height that should be used for the container that displays the details of the category

ACH

1234
createPaymentMethodManager(    type: "STRIPE_ACH",    options?: AchPaymentMethodManagerOptions): Promise<IAchPaymentMethodManager | null>
ts
copy

Create an instance of the IAchPaymentMethodManager, which can be used to manage ACH payment methods which also require an extra form and the mandate confirmation.

Parameters

type
"STRIPE_ACH"
The type of payment method to manage.
options
AchPaymentMethodManagerOptions

Options to configure the payment method manager.

Properties
stripePublishableKey
string

Stripe Publishable Key, used to interact with Stripe's SDK and collect the bank account details, necessary for the STRIPE_ACH payment method. The Publishable Key can be found in the Stripe Dashboard API keys.

Returns

Promise<IAchPaymentMethodManager | null>

A promise that resolves to an instance of IAchPaymentMethodManager or null.

IAchPaymentMethodManager
start
(data: T) => Promise<Validation | undefined>

Submits and validates the customer data starting the ACH payment method flow.

When the payment method is STRIPE_ACH, the required data T is:

12345
interface StripeAchFormData {    firstName: stringl;    lastName: string;    emailAddress: string}
typescript
copy
collectBankAccountDetails
() => Promise<void>

When the payment method is STRIPE_ACH, displays the Stripe UI to collect the bank account details.

Throws an error if the start method didn't run successfully or wasn't called before.

confirmMandate
() => Promise<void>

Submits the mandate confirmation. Should be triggered by a "Confirm" button next to the mandate text.

Throws an error if the methods start and collectBankAccountDetails weren't successfully called before.