BLOX - SDK reference

Welcome to the SDK Reference for Blox. This SDK simplifies secure online transactions by embedding PCI-compliant iframes into your checkout process to collect payment details. It then generates payment card tokens on the client side, enabling secure and hassle-free transactions. Browse this reference guide to get started and unlock the full capabilities of our solution.

For more information and examples, see Blox

BP Class

The namespace class contains the BloxController class for instantiating the secure blox instances and tokenizing the card details.

Creates an instance to control the secure blox instances and tokenize the card details.

BloxController Class

constructor(options): BloxController

NameTypeDescription
tokenstringToken from creating a blox session Server Session
fontsSources?string[]Optional. A list of custom font URLs to be applied to the blox instances. For an example, see Using Blox
style?BloxStyleOptional. CSS styles for styling the input elements. See Blox Style Reference

isAllValid: boolean

Property value is true when all blox instances are valid

createBlox(type: BloxType, options?: BloxOptions): Blox

Creates a secure blox instance to be mounted on an HTML element container.

NameTypeDescription
typeBloxTypeType of the blox instance to be created, cardNumber, cardCvv, cardExpiryDate
options?BloxOptionsOptional. Options object to config the blox instance

clearAll(): void

Clears input elements of all blox instances at once

validateAll(): void

Validates all blox instances at once

createPaymentCardToken(payload: PaymentCardTokenCreatePayload): Promise<PaymentCardToken>

Returns a token representation of the card data collected via the secure blox instances. If an error occurs it will be thrown using the standard JS mechanism. So to handle them the developer should use try catch or the catch method of the promise.

NameTypeDescription
payloadPaymentCardTokenCreatePayloadPayload required to create a payment card token

encryptCvv(): Promise<EncryptCvvResponsePayload>

Encrypts CVV collected via the secure blox instance. If an error occurs it will be thrown using the standard JS mechanism. So to handle them the developer should use try catch or the catch method of the promise.

BloxType

Type NameDescription
cardNumberShows an input element for the card number
cardExpiryDateShows an input element for the card expiration date
cardCvvShows an input element for the CVV code

PaymentCardTokenCreatePayload

NameTypeDescription
cardHolderNamestringCard holder name
singleUse?booleanOptional. Flag to create a single-use token, that will be deleted from the system upon usage.

PaymentCardToken

NameTypeDescription
typesingleUse|multiUseThe type of the payment card token, if single use the token can be used for payment only once
tokenstringThe payment card token to be used during payment
cardMaskedPaymentCardDetailsMasked card information plus additional card information like its brand, type, country
encryptedCvvstringDuring tokenization the API encrypted the CVV without storing it anywhere inside bridgerpay, you should provide it later on the payment request.

MaskedPaymentCardDetails

NameTypeDescription
maskedNumberstringMasked payment card number e.g.411111*******1113
binstringThe card's bin
last4DigitsstringThe card's last 4 digits
expireMonthnumberThe card's expiry month
expireYearnumberThe card's expiry year
holderNamestringCard holder name
brand?stringOptional. The card's brand, e.g.visa, mastercard, maestro
type?stringOptional. debit or credit type
issuer?stringOptional. An organization that issued the card
country?stringOptional. The country's ISO 3166 alpha-2 code where the card was issued

EncryptCvvResponsePayload

NameTypeDescription
encryptedCvvstringEncrypted CVV that wasn't stored anywhere inside bridgerpay, you should provide it later on the payment request.

Blox Class

The secure blox instance is responsible for setting up the iframe with an input form element to show on your checkout page and collecting one part of the user's card data.

mount(containerSelector: string): Promise

Mounts a secure blox instance to the DOM, onto the container where the input element should be rendered.

clear(): void

Clears the blox instance input element.

update(options: BloxOptions): void

At any time you can update the blox instance by calling the update method and providing a new set of options. The options will override whatever was provided during the blox instance creation.

BloxOptions

NameTypeDescription
placeholder?stringOptional. Placeholder for default text to show in an input element
skipLuhnValidation?booleanOptional. Flag to disable the Luhn validation
unmaskedCvv?booleanOptional. Flag to keep CVV unmasked.
cvvLength?numberOptional. Defaults to 3. If CVV Blox is used separately from Card Number Blox, the client must provide this value based on the rules defined by the client.
style?BloxStyleOptional. CSS styles for styling the input elements. See Blox Style Reference

on(event: BloxEvent, callback: (data: BloxEventPayload) => void): void

Binds an event listener to the blox instance input element, for events that are triggered when the value of an input element has been changed.

BloxEvent

  • change
  • focus
  • blur

BloxEventPayload

NameTypeDescription
emptybooleanWhether the input element is empty.
validbooleanWhether the card data is inserted and valid.
invalidbooleanWhether the card data is invalid.
dirtybooleanThe input element value was changed at least once
pristinebooleanThe input element value hasn't changed since loading
touchedbooleanThe input element was focused at least once since loading
untouchedbooleanThe input element hasn't been focused yet
errorstring|nullThe validation error
brand?stringOptional. Will be returned only for the cardNumber element type.

destroy(): void

Unmounts the blox instance from the DOM. You can only call this once.

Blox style

You can style the elements by providing the style object on the BloxController constructor options argument, on the createBlox method options argument, or on the update method options argument.

Style objects

The following is a list of object key names, representing the input element status to which you can apply styles. Note that the objects must be nested with the style object.

Property NameTypeDescription
baseCSSStyleDeclarationStyles that are inherited by the rest style objects
emptyCSSStyleDeclarationApplied when the element has no value
validCSSStyleDeclarationApplied when the element value is valid
invalidCSSStyleDeclarationApplied when the element value is invalid

Style object properties

Any valid CSS property can be used in camelCase notation applicable to an HTML input element.

Style object pseudo-classes and pseudo-elements

Any valid pseudo-CSS selector can be used to apply styles, for example:

  • :hover
  • :focus
  • ::placeholder
  • ::selection
  • :disabled
  • :hover::placeholder