Skip to main content

PurseHeadlessCheckoutPrimaryToken

Represents a primary token in the Purse checkout system. Primary tokens are saved payment methods like stored credit cards or digital wallet accounts.

Extends​

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​

PurseHeadlessCheckoutToken.additionalAssets

createdAt?​

optional createdAt?: string;

ISO 8601 date string indicating when the token was created. Useful for sorting saved payment methods chronologically.

Inherited from​

PurseHeadlessCheckoutToken.createdAt

description​

description: object;

Description holds all display values to describe the token in a UI. This is useful since the rendering of a token is limited to the CVV.

brand?​

optional brand?: string;

Brand of the token

expiration_date​

expiration_date: string;

Date at which the token is excepted to expire

holderName?​

optional holderName?: string;

Holder name of the token

label?​

optional label?: string;

Label is the way the partner formats the masked pan. Might be 4111********1111 or ****1111 etc.

masked_pan​

masked_pan: string;

Will contain displayable value of the PAN or the account email

disabled​

disabled: Readable<DisabledState | null>;

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

Inherited from​

PurseHeadlessCheckoutToken.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​

PurseHeadlessCheckoutToken.iconUrl

id​

id: string;

Unique identifier of the payment method

Examples​

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

Inherited from​

PurseHeadlessCheckoutToken.id

isFavorite​

isFavorite: Readable<boolean>;

Whether this token is the user's favorite payment method. Reflects IntegratedToken.favorite.

isSecondary​

isSecondary: false;

Indicates if the token is a secondary mean of payment

Overrides​

PurseHeadlessCheckoutToken.isSecondary

maxAmount​

maxAmount: number | null;

Maximum amount to use the payment method

Inherited from​

PurseHeadlessCheckoutToken.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​

PurseHeadlessCheckoutToken.method

minAmount​

minAmount: number | null;

Minimum amount to use the payment method

Inherited from​

PurseHeadlessCheckoutToken.minAmount

name​

name: string;

User-friendly name for the token, provided by the user during registration or by the payment partner. This name is used for display purposes in the UI to help users identify their saved payment methods.

Inherited from​

PurseHeadlessCheckoutToken.name

partner​

partner: string;

Partner associated with the payment method

Examples​

'hipay'
'paypal'

Inherited from​

PurseHeadlessCheckoutToken.partner

supportsHostedFields​

supportsHostedFields: boolean;

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

type​

type: "token";

Overrides​

PurseHeadlessCheckoutToken.type

Methods​

delete()​

delete(): Promise<void>;

Delete the token from the user's wallet

Returns​

Promise<void>

Throws​

Example​

token.delete();

Inherited from​

PurseHeadlessCheckoutToken.delete

edit()​

edit(payload): Promise<void>;

Edit the token's name

Parameters​

ParameterTypeDescription
payload{ name: string; }-
payload.namestring-

Returns​

Promise<void>

Throws​

Example​

token.edit({ name: 'New Name' });

Inherited from​

PurseHeadlessCheckoutToken.edit

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: {
       cvv: {
         target: '#card-cvv',
         placeholder: 'CVV',
       },
     },
     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;

Method to get the payment element. Creates the UI instance on first call. If you need to render a partner's UI, you will need a PaymentElement

Parameters​

ParameterTypeDescription
options?PurseHeadlessCheckoutUIOptions{PurseHeadlessCheckoutUIOptions | undefined}

Returns​

PurseHeadlessCheckoutPaymentElement

Example​

const paymentElement = token.getPaymentElement();
// Mount the payment element to your UI
paymentElement.appendTo('#payment-container');

setAsFavorite()​

setAsFavorite(): Promise<void>;

Toggle this token's favorite status. If it is already a favorite, it will be removed; otherwise it will be marked as the user's favorite. Persists the change via the wallet API.

Returns​

Promise<void>

Throws​

Example​

await token.setAsFavorite(); // marks as favorite
await token.setAsFavorite(); // removes favorite status

setAsPrimarySource()​

setAsPrimarySource(): void;

Use this method if you want to change which primary to use in the split. This can be useful if you have mounted multiple primary payment elements (ie. Wallet AND installments for instance).

Returns​

void

Throws​

Example​

token.setAsPrimarySource();