Initialise the library
  • 18 Dec 2023
  • 20 Minutes to read
  • Dark
    Light

Initialise the library

  • Dark
    Light

Article summary

Initialise the library within the <script> tag, or within a JavaScript file, of the payment page. This must be placed after all the payment components.

An example of initialising the library:

<script> 
     let pay360DC = new Pay360DC(config);
     pay360DC.initiatePayment();
</script> 

This initialisation requires a config object and makes a call to the initiatePayment function, which are described below.

Config object

The config object is required to:

  • Provide parameters to the library

  • Customise the look and feel of the Direct Checkout UI (optional)

  • Handle the Direct Checkout response.

The attributes available in the config object are described below.

Mandatory attributes

Attribute

Description

Source

isvId

ID for the integrator, used during payment processing

Data type: Integer

Refer to Prerequisites - Credentials section

transactionId

ID for a transaction

Data type: Integer

Payment intent response:
transaction.transactionId

sessionId

ID for a transaction session

Payment intent response:
transaction.sessionId

callbackResponse

Function that handles the transaction processing response from Direct Checkout

Refer to Callback response section below

Specified by integrator

An example of setting mandatory attributes in the config object:

<script>
  let config; 
  config = { 
  		isvId:  parseInt(isvId),
  		transactionId:  parseInt(transactionId), 
		sessionId:  sessionId,
		callbackResponse:  callbackResponse
  } 
</script>	  

Callback response

The callbackResponse attribute is a reference to a function that must be written to handle the response from Direct Checkout. Refer to Processing a payment with Direct Checkout - Handle payment processing response section.

function callbackResponse(status, type, response) 
{ 
  //  Handle payment processing response 
} 

Important: The callback response will not provide the final status of the transaction. Since the response is returned to the browser, the integrator must query for a final payment status by making a sever-to-server request.

Optional attributes

Attribute

Description

Styles

Customise styling of the payment components

Refer to Styling

Localisations

Customise text in the payment controls

Refer to Localisation

defaultFocus

Default browser focus on a component when the page is loaded

Typically set to “pay360-cardholder-data” which will set the focus on the card input field

cardholderName

Default value for the Cardholder name field

applepayCaptureBillingAddress

Billing address may be captured via Apple Pay

Possible values: true, false

Default value is false; refer to the Apple Pay Billing Address section below

initiatePaymentCallbackResponse

Data type: function

Function will be called with active payment methods through Direct Checkout

Refer to Initiate Payment Callback Response section below

card.layoutType

Layout of the card details fields

Possible Values: inline, default

Default value is default

card.hideCardholderName

Display of cardholder name field

Possible values: true, false
Default
value is false

labelPosition

Cards component labels may be to the right hand side of the field
Possible values: left-justified,
 right-justified’

Note: config.labelPosition and config.inputLabelInsideBorder cannot be used together

inputLabelInsideBorder

Cards component labels may be displayed in material design fashion; labels are initially inside the field and once focused or filled the label will display above the field

Values: true, false

Note: config.labelPosition and config.inputLabelInsideBorder cannot be used together

googlePay.buttonType

Google Pay button type

Possible values: book, buy (default), checkout, donate, order, pay, plain, subscribe

googlePay.buttonLocale

Google Pay button language

Possible values: 'en' | 'ar' | 'bg' | 'ca' | 'cs' | 'da' | 'de' | 'el' | 'es' | 'et' | 'fi' | 'fr' | 'hr' | 'id' | 'it' | 'ja' | 'ko' | 'ms' | 'nl' | 'no' | 'pl' | 'pt' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'th' | 'tr' | 'uk' | 'zh'

'sv' | 'th' | 'tr' | 'uk' | 'zh';

'sv' | 'th' | 'tr' | 'uk' | 'zh';

Refer to https://en.wikipedia.org/wiki/List_of_ISO_639- 1_codes

An example of setting optional attributes in the config object:

<script>
  let config; 
  config = { 
  		isvId:  parseInt(isvId),
  		transactionId:  parseInt(transactionId), 
		sessionId:  sessionId,
		callbackResponse:  callbackResponse
        styles:  { 
  	    //  See Styling 
        }, 
        localisations:  { 
  	    //  See Localisation 
        }, 
        defaultFocus: pay360-cardholder-data,
        applePayCaptureBillingAddress: "false",
        inputLabelInsideBorder: "false",
        card: {
        layoutType: "default"
        },
        labelPosition: "left-justified",
        googlePay: {
        buttonType: "pay",
        buttonLocale: "en"
  } 
</script>	

Apple Pay billing address

The "applepayCaptureBillingAddress" attribute enables the capture of a billing address via Apple Pay. This is a conditional attribute based on your requirements.

  • If your integration is not supplying billing details in the payment intent, and “applepayCaptureBillingAddress” is set to true, a billing address may be captured by Apple Pay.

  • If your integration is not supplying billing details in the payment intent, and “applepayCaptureBillingAddress” is set to false, no billing address will be captured.

  • If your integration is supplying billing details in the payment intent, and “applepayCaptureBillingAddress” is set to true, any billing address captured by Apple Pay will overwrite the data from the payment intent.

  • If your integration is supplying billing details in the payment intentand “applepayCaptureBillingAddress” is set to false, the billing address from the payment intent will be used.

We will require a billing email to provide an Access PaySuite email receipt, which may only be sent in the payment intent.

Initiate Payment function

When the payer is ready to choose their payment method, the initiatePayment function on the pay360DC object should be made. This will verify that the configuration provided is valid.

The response to this method will trigger a callback event for the optional function provided for “config.initiatePaymentCallbackResponse” (refer to Optional Attributes section below). The function will contain a parameter with a list of the allowed payment methods. The integrator can use this function to perform specific handling. Possible use cases are:

  • Present a message showing a list of payment methods which are accepted.

  • Hide text labels, messages and styling related to payment methods which are not accepted.

Initiate Payment Callback Response

InitiatePaymentCallbackResponse is a reference to a function that must be written to handle the response from Direct Checkout when initialized using the initiatePayment function.

This callback function has single parameter of “allowedMethods” which is of type string array. This will contain an array of allowed payment methods. The possible values of the array items are CARD, APPLE_PAY, GOOGLE_PAY, and PAY_BY_BANK_ACCOUNT.

The ISV can modify their DOM based on the allowed payment methods to facilitate their end user with only allowed payment methods.

Note: Direct Checkout handles the visibility of the components. Only elements of the integrator payment page need to be handled by this function.

An example of implementing the callback function:

initiatePaymentCallback(allowedMethods: string[]) 
{
// Integrator can modify their DOM based on the values of the allowedMethods.
}


Was this article helpful?