Skip to main content

PurseHeadlessCheckout

Properties​

amountSplit​

readonly amountSplit: Readable<PaymentSplit[]>;

Splits represent the repartition between the primary payment method and the secondary payment methods.

PurseHeadlessCheckoutPaymentSplit

Example​

headlessCheckout.amountSplit.subscribe((splits: PurseHeadlessCheckoutPaymentSplit[]) => {
   console.log('The payment composition changed', splits);
});

currency​

readonly currency: Readable<string>;

currentSessionID​

readonly currentSessionID: Readable<string | null>;

Current paymentSessionID readable value;

isInformationRequest​

readonly isInformationRequest: Readable<boolean>;

Indicates whether the current session is an information request (data collection) session. In such sessions there is no amount to pay — the purpose is gathering payment information (e.g. registering a card) for later use. Only protocols with registration_mode: "OFF_SESSION" are available in this mode.

Example​

headlessCheckout.isInformationRequest.subscribe((isInformationRequest: boolean) => {
   if (isInformationRequest) {
     // Adapt the UI: no amount to display, submit stores the card for later use
   }
});

isPaymentFulfilled​

readonly isPaymentFulfilled: Readable<boolean>;

This property indicates if the payment can be submitted.

Example​

headlessCheckout.isPaymentFulfilled.subscribe((isFulfilled: boolean) => {
   if(isFulfilled) {
     enablePayButton();
   }else{
     disablePayButton();
   }
});

paymentMethods​

readonly paymentMethods: Readable<PurseHeadlessCheckoutPaymentMethod[]>;

List of available payment methods for the checkout. Each payment-element in the array represents a payment method with its associated properties.

Example​

headlessCheckout.paymentMethods.subscribe((methods: PurseCheckoutPaymentMethod[]) => {
   console.log('The payment methods changed', methods);
   // Perhaps update the UI with the new methods
});

paymentTokens​

readonly paymentTokens: Readable<PurseHeadlessCheckoutPaymentToken[]>;

List of available payment tokens for the checkout. Each payment-element in the array represents a payment token with its associated properties.

Example​

headlessCheckout.paymentTokens.subscribe((tokens: PurseCheckoutPaymentToken[]) => {
  console.log('The payment tokens changed', tokens);
  // Perhaps update the UI with the new tokens
});

remainingAmountToPay​

readonly remainingAmountToPay: Readable<number>;

The remaining amount to pay represents the amount that is left to pay after the secondary payment method(s) has been used.

Example​

headlessCheckout.remainingAmountToPay.subscribe((amount: number) => {
   console.log('Perhaps update the text in your pay button', amount);
});

sessionState​

readonly sessionState: Derived<PurseHeadlessCheckoutSessionState, [Writable<PurseHeadlessCheckoutSessionState>]>;

The current state of the checkout session. It can be one of the following values:

  • 'idle': The session is idle and not yet initialized.
  • 'ready': The session is initialized and ready for payment method selection.
  • 'submitting': The payment is being submitted.
  • 'submitted': The session was validated successfully and is now spent. Further submissions are refused, since the API accepts one validation per session.
  • 'expired': The session has expired.
  • 'error': An error occurred with the session, including a validation the API refused or a payment it declined. The session was not consumed, so submitting again is allowed.

Example​

headlessCheckout.sessionState.subscribe((state: PurseHeadlessCheckoutSessionState) => {
   console.log('The session state changed', state);
   if(state === 'expired') {
     alertUserSessionExpired();
   }
});

Methods​

clearPrimarySplit()​

clearPrimarySplit(): void;

Clears the primary split from the amount share. Nothing happens if the primary split is already cleared.

Returns​

void

Example​

headlessCheckout.clearPrimarySplit();

deleteAllTokens()​

deleteAllTokens(): Promise<void>;

Remove all tokens from the provided wallet session

Returns​

Promise<void>

Throws​

Example​

headlessCheckout.deleteAllTokens();

getPaymentElement()​

getPaymentElement(options): 
  | PurseHeadlessCheckoutPaymentElement
  | PurseHeadlessCheckoutHostedFields;

Shortcut to instantiate a payment element directly from the checkout, without iterating through paymentMethods to find a method first.

Behaviour:

  • hostedForm and hostedFields are mutually exclusive — when both are set, hostedForm wins and a warning is emitted.
  • method is required for hostedForm. For hostedFields it can be omitted, in which case the first primary method on partner is used.
  • When the resolved method does not support hosted fields, a warning is logged but the call still returns the hosted-fields instance.

Parameters​

ParameterTypeDescription
optionsPurseHeadlessCheckoutGetPaymentElementOptionsPurseHeadlessCheckoutGetPaymentElementOptions

Returns​

| PurseHeadlessCheckoutPaymentElement | PurseHeadlessCheckoutHostedFields

Throws​

Example​

const el = checkout.getPaymentElement({
  partner: 'ingenico',
  method: 'creditcard',
  theme: {},
  hostedForm: {},
});
el.appendTo('#container');

setSession()​

Call Signature​

setSession(widgetData): Promise<void>;

Updates the session with the provided session data.

Parameters​
ParameterTypeDescription
widgetDatastringThe session data. Can be either an encoded string (V2) or a payment session object (V1).
Returns​

Promise<void>

Throws​
Example​
headlessCheckout.setSession(paymentSession);

Call Signature​

setSession(widgetData): Promise<void>;

Updates the session with the provided session data.

Parameters​
ParameterTypeDescription
widgetDataLegacyPaymentSessionThe session data. Can be either an encoded string (V2) or a payment session object (V1).
Returns​

Promise<void>

Throws​
Example​
headlessCheckout.setSession(paymentSession);

setWalletSession()​

setWalletSession(walletSession): Promise<void>;

Sets the wallet session. The wallet session is used to retrieve and manage the user's stored card tokens.

Parameters​

ParameterTypeDescription
walletSessionOnePayWalletSession-

Returns​

Promise<void>

Throws​

PurseHeadlessCheckoutError SET_WALLET_SESSION_FAILED
If setting the wallet session fails

Example​

headlessCheckout.setWalletSession(walletSession);

submitPayment()​

submitPayment(skipOnBeforeValidateHook?): Promise<void>;

Submits the current payment configuration for processing. This will validate and process all payment methods in the current split configuration.

Resolves without doing anything when a submission is already in flight, or when the session has already been validated successfully. Watch sessionState to tell the two apart.

Parameters​

ParameterType
skipOnBeforeValidateHook?boolean

Returns​

Promise<void>

Throws​

Example​

try {
  // Configure payment methods and amounts
  await primaryMethod.setAsPrimarySource();
  await secondaryToken.take(50.00);

  // Submit the payment
  await checkout.submitPayment();
  console.log('Payment successful!');
} catch (error) {
  console.error('Payment failed:', error);
}

teardown()​

teardown(): void;

Cleans up resources and removes event listeners.

Returns​

void

Example​

headlessCheckout.teardown();

getConfigFromParams()​

static getConfigFromParams(checkoutParams, apiPaths?): PurseHeadlessCheckoutV1Params & object;

Get the config from params

Parameters​

ParameterTypeDescription
checkoutParams| string | PurseHeadlessCheckoutV1ParamsThe checkoutParams data for initializing the checkout.
apiPaths?APIPathsdev purposes only to override the APi URL's

Returns​

PurseHeadlessCheckoutV1Params & object