Skip to main content

PurseHeadlessCheckoutPrimaryMethod

Represents a primary payment method in the Purse checkout system. Primary methods are the main payment options like credit cards, digital wallets, or bank transfers.

Example​

// Get payment element for a primary method
const primaryMethod: PurseHeadlessCheckoutPrimaryMethod = ...
const element = await primaryMethod.getPaymentElement({
  hostedForm: {
    panPlaceholder: 'Enter your card number',
    cvvPlaceholder: 'Enter your CVV'
    // Add more options here
  }
});

// Mount the payment element to your UI
element.appendTo('#payment-container');

Extends​

Extended by​

Properties​

additionalAssets​

additionalAssets: CardSchemeAsset[];

Additional assets associated with this payment item, primarily card scheme logos.

For credit card methods with vault support, this contains one entry per supported card scheme (e.g. Visa, Mastercard, CB). For all other payment methods the array is empty.

Each asset provides a CDN URL and a human-readable label suitable for display and accessibility purposes.

Example​

// React
{method.additionalAssets.map(asset => (
  <img key={asset.url} src={asset.url} alt={asset.label} />
))}

Inherited from​

PurseHeadlessCheckoutMethod.additionalAssets

canBeRegistered​

canBeRegistered: boolean;

Whether the user can choose to register this method. True only for save_token_mode values PREFER and PREFER_NO. When false, the save-token checkbox must not be shown; the backend enforces the registration policy (ALWAYS/NEVER) without a frontend signal.

Inherited from​

PurseHeadlessCheckoutRegisterable.canBeRegistered

disabled​

disabled: Readable<DisabledState | null>;

Indicates if the payment method is disabled with an error code and message DisabledState error code and message

Inherited from​

PurseHeadlessCheckoutMethod.disabled

iconUrl​

iconUrl: string;

Absolute URL of the payment method icon on the Purse CDN.

The URL is stable and environment-aware (sandbox vs production). The icon is an SVG file that respects the brand guidelines of the payment partner. It can be used directly in an <img> tag or as a CSS background image without any further processing.

Example​

// React
<img src={method.iconUrl} alt={method.method} />

Inherited from​

PurseHeadlessCheckoutMethod.iconUrl

id​

id: string;

Unique identifier of the payment method

Examples​

'hipay-bancontact'
'illicado-giftcard'
'aci-creditcard'

Inherited from​

PurseHeadlessCheckoutMethod.id

integrationType?​

optional integrationType?: "redirection" | "popup";

Some partners are available under several forms For instance paypal or klarna can exist as a redirection or as a popup

isSecondary​

isSecondary: false;

Indicates if the payment method is a secondary mean of payment

Overrides​

PurseHeadlessCheckoutMethod.isSecondary

limit​

limit: number | null;

Amount limit for the payment method (null if no limit)

Inherited from​

PurseHeadlessCheckoutMethod.limit

maxAmount​

maxAmount: number | null;

Maximum amount to use the payment method

Inherited from​

PurseHeadlessCheckoutMethod.maxAmount

method​

method: string;

Type of payment method, it can be a card, a wallet, a bank transfer, etc.

Examples​

'applepay'
'googlepay'
'creditcard'

Inherited from​

PurseHeadlessCheckoutMethod.method

minAmount​

minAmount: number | null;

Minimum amount to use the payment method

Inherited from​

PurseHeadlessCheckoutMethod.minAmount

partner​

partner: string;

Partner associated with the payment method

Examples​

'hipay'
'paypal'

Inherited from​

PurseHeadlessCheckoutMethod.partner

position​

position: number;

Position of the payment method in the list

Inherited from​

PurseHeadlessCheckoutMethod.position

registration​

registration: Readable<RegistrationState>;

This property exposes if the mean of payment is bound for registration upon validate.

Inherited from​

PurseHeadlessCheckoutRegisterable.registration

saveTokenMode​

saveTokenMode: SaveTokenMode;

The effective save_token_mode resolved for this mean of payment (ALWAYS / PREFER / PREFER_NO / NEVER), including the save_token boolean fallback. Exposed for consumers that need to distinguish why registration is or isn't user-controllable — e.g. ALWAYS forces registration silently, with canBeRegistered false like NEVER.

Inherited from​

PurseHeadlessCheckoutRegisterable.saveTokenMode

simulable​

simulable: boolean;

Whether the method can provide loan simulation or not

supportsHostedFields​

supportsHostedFields: boolean;

Whether the method supports hosted fields (secure card input via iframes)

type​

type: "method";

Inherited from​

PurseHeadlessCheckoutMethod.type

Methods​

getElementInstance()​

getElementInstance(): 
  | PurseHeadlessCheckoutPaymentElement
  | PurseHeadlessCheckoutHostedFields
  | undefined;

Returns the currently active element instance — whichever of getPaymentElement / getHostedFields was last called.

Returns​

| PurseHeadlessCheckoutPaymentElement | PurseHeadlessCheckoutHostedFields | undefined

getHostedFields()​

getHostedFields(options?): PurseHeadlessCheckoutHostedFields;

Creates and returns a hosted fields UI instance for this payment method.

Parameters​

ParameterTypeDescription
options?HostedFieldsOptionsHostedFieldsOptions: settings for the hosted fields

Returns​

PurseHeadlessCheckoutHostedFields

A hosted fields instance for this payment method

Example​

  const hostedFields = primaryMethod.getHostedFields({
     fields: {
       pan: {
         target: '#card-number',
         placeholder: 'Card number',
       },
       cvv: {
         target: '#card-cvv',
         placeholder: 'CVV',
       },
       expirationDate: {
         target: '#card-expiration-date',
         placeholder: 'MM / YY',
       },
     },
     theme: {
       global: {
         fontSrc: 'https://fonts.googleapis.com/css?family=Roboto',
       },
       input: {
         color: '#333',
         fontSize: '16px',
         fontFamily: 'Arial, sans-serif',
         backgroundColor: '#fff',
         fontWeight: '400',
         ':valid': {
           color: 'green',
         },
       }
     }
   });
  await hostedFields.render();

getPaymentElement()​

getPaymentElement(options?): PurseHeadlessCheckoutPaymentElement;

Creates and returns a payment element UI instance for this payment method. The instance is created only on the first call and cached for subsequent calls.

Parameters​

ParameterTypeDescription
options?PaymentElementOptionsOptional UI customization settings for the payment element

Returns​

PurseHeadlessCheckoutPaymentElement

A payment element instance for this payment method

Example​

const paymentElement = primaryMethod.getPaymentElement({
  hostedForm: {
    panPlaceholder: 'Enter your card number',
    cvvPlaceholder: 'Enter your CVV'
    // Add more options here
  }
})
await paymentElement.appendTo('#payment-container');

register()​

register(value?, params?): Promise<void>;

Mark this mean of payment for registration upon validate.

Parameters​

ParameterTypeDescription
value?boolean{boolean} true to register, false to unregister
params?{ name?: string; }-
params.name?string-

Returns​

Promise<void>

Example​

item.register(true);

Throws​

Inherited from​

PurseHeadlessCheckoutRegisterable.register

setAsPrimarySource()​

setAsPrimarySource(): void;

Changes the active primary payment source in the current payment split. Use this when you have multiple primary payment elements mounted (e.g., Wallet AND installments).

Returns​

void

Throws​

Example​

// Switch to this payment method as the primary source
await method.setAsPrimarySource();

simulateLoan()​

simulateLoan(product): Promise<LoanSimulation>;

Some method are 'simulable' and can give a loan simulation if provided with a product description

Parameters​

ParameterType
productLoanProduct

Returns​

Promise<LoanSimulation>

Throws​

  • PurseHeadlessCheckoutError INVALID_LOAN_SIMULATION
    If the method is not simulable or when an error happened during the simulation.

Example​

await method.simulateLoan({ amount: 200, shipments: [], currency_code: 'EUR',...  });