Implementation

Headless Checkout by OrkestaPay

Once you have the OrkestaPay script instantiated, you need to create an instance of OrkestaPayCard, which can be done in several ways:

Initialize Card via DOM Input References

To reference the card form inputs, you can use either the element ID or the input reference (recommended). The defined input references are:

• card_number (Required): Can be an HTMLInputElement reference or the ID as a string.

• expiration_date (Required): Can be an HTMLInputElement reference, the ID as a string, or an object with properties expiration_month and expiration_year if the month and year are separated into individual inputs.

• expiration_month (Required): Can be an HTMLInputElement reference or the ID as a string.

• expiration_year (Required): Can be an HTMLInputElement reference or the ID as a string.

• verification_code (Required): Can be an HTMLInputElement reference or the ID as a string.

• holder_name (Optional): Can be an HTMLInputElement reference or the ID as a string. If not provided, this data must be given during tokenization, which is described in the “Tokenize a Card” section.

• holder_last_name (Optional): Can be an HTMLInputElement reference or the ID as a string.

Example of initialization using DOM input references (recommended) with a single expiration date input:

async function createOrkestaPayCard() {
    const card_number = document.getElementById('card-number');
    const expiration_date = document.getElementById('card-expiration');
    const verification_code = document.getElementById('card-verification-code');
    const holder_name = document.getElementById('holder-name');
    const holder_last_name = document.getElementById('holder-last-name');

    const orkestapay_card = await orkestapay.createCard({
        card_number,
        expiration_date,
        verification_code,
        holder_name,
        holder_last_name,
    });

    return orkestapay_card;
}

Example of initialization using DOM input IDs with separate expiration date inputs and without promotions configuration:

async function createOrkestaPayCard() {
    const card_number = 'card-number';
    const expiration_month = 'card-expiration-month';
    const expiration_year = 'card-expiration-year';
    const verification_code = 'card-verification-code';
    const holder_name = 'holder-name';
    const holder_last_name = 'holder-last-name';

    const orkestapay_card = await orkestapay.createCard({
        card_number,
        expiration_date: {
            expiration_month,
            expiration_year,
        },
        verification_code,
        holder_name,
        holder_last_name,
    });

    return orkestapay_card;
}

Example of initialization without parameters and using the mount method to reference DOM inputs:

async function createOrkestaPayCard() {
    const orkestapay_card = await orkestapay.createCard();

    const card_number = document.getElementById('card-number');
    const expiration_month = document.getElementById('card-expiration-month');
    const expiration_year = document.getElementById('card-expiration-year');
    const verification_code = document.getElementById('card-verification-code');

    await orkestapay_card.mount({
        card_number,
        expiration_date: {
            expiration_month,
            expiration_year,
        },
        verification_code,
    });

    return orkestapay_card;
}

Example of initialization without parameters and without using the mount method to reference DOM inputs:

async function createOrkestaPayCard() {
  const orkestapay_card = await orkestapay.createCard();
  return orkestapay_card;
}

Tokenize a Card

Tokenizing a card depends on whether the input references were provided or not, and whether the holder name reference was included. The tokenization process requires an optional object (depending on how the OrkestaPayCard instance was configured) with the following properties:

• card (Optional): This object is required when the holder name was not provided via an input reference or when no input references were used.

• card_number (Optional/Required): Card number as a string, required only if the corresponding card form input was not referenced.

• expiration_date (Optional/Required): Expiration date in mm/yy or mm/yyyy format as a string, required only if the corresponding card form input was not referenced.

• verification_code (Optional/Required): Verification code as a string, required only if the corresponding card form input was not referenced.

• holder_name (Required): Required only if it was the only required property not referenced via the card form input.

• holder_last_name (optional).

• customer_id (Optional): Only when the customer was created/obtained previously via the OrkestaPay API.

• one_time_use (Optional): Boolean value. If customer_id is not provided, this should always be true.

Variables for the tokenization examples in this section:

const is_sandbox = true;
const merchant_id = '{YOUR_MERCHANT_ID}';
const public_key = '{YOUR_PUBLIC_KEY_OR_DEVICE_KEY}';
const orkestapay = initOrkestaPay({ is_sandbox, merchant_id, public_key });


const card_number_id = 'card-number';
const expiration_date_id = 'card-expiration';
const expiration_month_id = 'card-expiration-month';
const expiration_year_id = 'card-expiration-year';
const verification_code_id = 'card-verification-code';
const holder_name_id = 'holder-name';
const holder_last_name_id = 'holder-last-name';


const card_number = document.getElementById(card_number_id);
const expiration_date = document.getElementById(expiration_date_id);
const expiration_month = document.getElementById(expiration_month_id);
const expiration_year = document.getElementById(expiration_year_id);
const verification_code = document.getElementById(verification_code_id);
const holder_name = document.getElementById(holder_name_id);
const holder_last_name = document.getElementById(holder_last_name_id);

Examples for Tokenizing Cards

In this example, a payment method is created by tokenizing a card with references to the card number, expiration date using a single input, verification code, holder name, and holder last name. As no parameters are passed, a console warning will indicate that one_time_use will be set to true:

(async function tokenize() {
  const orkestapay_card = await orkestapay.createCard({
    card_number,
    expiration_date,
    verification_code,
    holder_name,
    holder_last_name,
  });

  const payment_method = await orkestapay_card.createToken();
})();

In this example, a payment method is created by tokenizing a card with references to the card number, expiration date using a single input, verification code, holder name, and holder last name. The one_time_use property is set to true as no customer_id is provided, so it cannot be saved for future use:

(async function tokenize() {
    const orkestapay_card = await orkestapay.createCard({
        card_number,
        expiration_date,
        verification_code,
        holder_name,
        holder_last_name,
    });

    const one_time_use = true;
    const payment_method = await orkestapay_card.createToken({ one_time_use });
})();

In this example, a payment method is created by tokenizing a card with references to the card number, expiration date using separate month and year inputs, verification code, and promotions configuration. The one_time_use property is set to false as customer_id is provided and this payment method can be saved for future use for this specific customer:

(async function tokenize() {
    const orkestapay_card = await orkestapay.createCard();

    await orkestapay_card.mount({
        card_number: card_number_id,
        expiration_date: {
            expiration_month: expiration_month_id,
            expiration_year: expiration_year_id,
        },
        verification_code: verification_code_id,
    });

    const holder_name = 'John Doe';
    const card = { holder_name };
    const one_time_use = false;
    const customer_id = '569637be-010c-4790-a2da-9c30bd9374c5';

    const payment_method = await orkestapay_card.createToken({
        card,
        customer_id,
        one_time_use,
    });
})();

In this example, the card form inputs are not referenced; instead, the data is passed during tokenization:

(async function tokenize() {
    const orkestapay_card = await orkestapay.createCard();

    const card_number = '4242 4242 4242 4242';
    const expiration_date = '12/28';
    const verification_code = '123';
    const holder_name = 'John';
    const holder_last_name = 'Doe';

    const card = {
        card_number,
        expiration_date,
        verification_code,
        holder_name,
        holder_last_name,
    };

    const one_time_use = false;
    const customer_id = '569637be-010c-4790-a2da-9c30bd9374c5';

    const payment_method = await orkestapay_card.createToken({
        card,
        customer_id,
        one_time_use,
    });
})();

Manage Validations of Card Form Input References

When you provide the references for the card form inputs, real-time validation is performed.

Assuming that an instance of OrkestaPayCard:

const is_sandbox = true;
const merchant_id = '{YOUR_MERCHANT_ID}';
const public_key = '{YOUR_PUBLIC_KEY_OR_DEVICE_KEY}';
const orkestapay = initOrkestaPay({ is_sandbox, merchant_id, public_key });
let orkestapay_card;

(async function createOrkestaPayCard() {
  orkestapay_card = await orkestapay.createCard();
})();

We have the following events:

• orkestapay_card.card_number.errors$

• orkestapay_card.expiration_date.errors$

• orkestapay_card.verification_code.errors$

• orkestapay_card.holder_name.errors$

• orkestapay_card.holder_last_name.errors$

Where each one is an observable that will be emitting the errors that are detected when the user is entering their card data, the following example shows how to subscribe to the errors of card_number:

orkestapay_card.card_number.errors$.subscribe((error) => {
  if (error) console.error(error.code, error.message, error);
});

The type of errors available is described in the section on Error Models and Entities .

Terminating the OrkestaPayCard Instance

When the OrkestaPayError instance is no longer needed, it must be unmounted to complete and close all the generated events, for this the unmount method is used:

(async function destroyCard() {
  await orkestapay_card.unmount();
})();

Important: Even if the card form input references have not been passed, it is important to unmount the instance of OrkestaPayCard.

Models and entities

OrkestaPayCard models and entities

Orkesta PayCard Class

class OrkestaPayCard {
  public readonly card_number!: OrkestaPayCardNumber;
  public readonly expiration_date!: OrkestaPayCardExpirationDate;
  public readonly verification_code!: OrkestaPayCardVerificationCode;
  public readonly holder_name!: OrkestaPayHolderName;
  public readonly holder_last_name!: OrkestaPayHolderLastName;


  public mount(mount_params: MountCardParams): Promise<boolean>;
  public isAlreadyMounted(): boolean;
  public validate(): void;
  public isValid(): boolean;
  public isInvalid(): boolean;
  public isCompleted(): boolean;
  public unmount(): Promise<boolean>;
  public createToken(params?: CreateTokenParams): Promise<PaymentMethodCard>;
}

MountCardParams Class

class MountCardParams {
  public card_number!: HTMLInputElement | string;
  public expiration_date!: MountCardExpirationParams | HTMLInputElement | string;
  public verification_code!: HTMLInputElement | string;
  public holder_name?: HTMLInputElement | string;
  public holder_last_name?: HTMLInputElement | string;
  public promotions_params!: MountCardPromotionParams;
}

MountCardExpirationParams class

class MountCardExpirationParams {
  public expiration_month!: HTMLInputElement | string;
  public expiration_year!: HTMLInputElement | string;
}

MountCardPromotionParams Class

class MountCardPromotionParams {
  public currency!: string;
  public total_amount!: number | string;
}

CreateTokenParams class

class CreateTokenParams {
  public card?: CreateTokenCardParams;
  public one_time_use?: boolean;
  public customer_id?: string;
}

CreateTokenCardParams class

class CreateTokenCardParams {
  public card_number?: string;
  public expiration_date?: string;
  public verification_code?: string;
  public holder_name!: string;
  public holder_last_name?: string;
}

Orkesta classPayCardNumber

class OrkestaPayCardNumber {
  public readonly field_name: string;
  public readonly promotions$: Observable<CardPromotion[]>;
  public readonly errors$: Observable<OrkestaPayError | null>;

  public mount(mount_params: OrkestaPayCardNumberMountParams): Promise<boolean>;
  public isAlreadyMounted(): boolean;
  public validate(): void;
  public isValid(): boolean;
  public isInvalid(): boolean;
  public isCompleted(): boolean;
  public unmount(): Promise<boolean>;
  public getErrors(): OrkestaPayError | null;
  public mountPromotions(promotions_params: MountCardPromotionParams): Promise<boolean>;
  public getBin(): string;
  public getLastFour(): string;
  public setCardNumber(card_number: string): void;
}

Orkesta classPayCardNumberMountParams

class OrkestaPayCardNumberMountParams {
  card_number!: HTMLInputElement | string;
  promotions_params!: MountCardPromotionParams;
}

CardPromotion Class

class CardPromotion {
  public type!: string;
  public installments!: number[];
}

Orkesta classPayCardExpirationDate

class OrkestaPayCardExpirationDate {
  public readonly field_name: string;
  public readonly errors$: Observable<OrkestaPayError | null>;

  public mount(mount_params: HTMLInputElement | string): Promise<boolean>;
  public isAlreadyMounted(): boolean;
  public validate(): void;
  public isValid(): boolean;
  public isInvalid(): boolean;
  public isCompleted(): boolean;
  public unmount(): Promise<boolean>;
  public getErrors(): OrkestaPayError | null;
  public getSeparator(): string;
  public setSeparator(separator: string): void;
  public getDate(): string;
  public setDate(expiration_date: OrkestaPayCardExpirationDateParams | string): void;
  public getMonth(): string;
  public setMonth(month: string): void;
  public getYear(): string;
  public setYear(year: string): void;
}

Orkesta classPayCardExpirationDateParams

class OrkestaPayCardExpirationDateParams {
  public expiration_month!: string;
  public expiration_year!: string;
}

Orkesta classPayCardVerificationCode

class OrkestaPayCardVerificationCode {
  public readonly field_name: string;
  public readonly errors$: Observable<OrkestaPayError | null>;

  public mount(mount_params: HTMLInputElement | string): Promise<boolean>;
  public isAlreadyMounted(): boolean;
  public validate(): void;
  public isValid(): boolean;
  public isInvalid(): boolean;
  public isCompleted(): boolean;
  public unmount(): Promise<boolean>;
  public getErrors(): OrkestaPayError | null;
  public setVerificationCode(verification_code: string): void;
}

OrkestaPayHolderName class

class OrkestaPayHolderName {
  public readonly field_name: string;
  public readonly errors$: Observable<OrkestaPayError | null>;

  public mount(mount_params: HTMLInputElement | string): Promise<boolean>;
  public isAlreadyMounted(): boolean;
  public validate(): void;
  public isValid(): boolean;
  public isInvalid(): boolean;
  public isCompleted(): boolean;
  public unmount(): Promise<boolean>;
  public getErrors(): OrkestaPayError | null;
  public getHolderName(): string;
  public setHolderName(holder_name: string): void;
}

OrkestaPayHolderLastName Class

class OrkestaPayHolderLastName {
  public readonly field_name: string;
  public readonly errors$: Observable<OrkestaPayError | null>;

  public mount(mount_params: HTMLInputElement | string): Promise<boolean>;
  public isAlreadyMounted(): boolean;
  public validate(): void;
  public isValid(): boolean;
  public isInvalid(): boolean;
  public isCompleted(): boolean;
  public unmount(): Promise<boolean>;
  public getErrors(): OrkestaPayError | null;
  public getHolderLastName(): string;
  public setHolderLastName(holder_last_name: string): void;
}

Error Models and Entities

OrkestaPayError Class

class OrkestaPayError extends Error {
    public override readonly name: string = this.constructor.name;

    constructor(public readonly code: ORKESTAPAY_CARD_FORM_VALIDATOR_ERROR, message: string) {
        super(message);
    }
}

Enumerator ORKESTAPAY_CARD_FORM_VALIDATOR_ERROR

enum ORKESTAPAY_CARD_FORM_VALIDATOR_ERROR {
  REQUIRED = 'REQUIRED',
  MIN_LENGTH = 'MIN_LENGTH',
  MAX_LENGTH = 'MAX_LENGTH',
  INVALID_LENGTH = 'INVALID_LENGTH',
  INVALID_FORMAT = 'INVALID_FORMAT',
  EXPIRED = 'EXPIRED',
  INVALID = 'INVALID',
}