SDK CHECKOUTS #

Version: 1.1.1
Released: 2024/05/09

Copyrighted by lddPay

Checkout SDK Documentation #

General #

For the checkout page, a wide range of settings is available through the admin panel, for example, placing your own logo, changing the colors of basic elements. But if these opportunities are not enough to ensure corporate style, design, merchants also have the option of uploading their own checkout page on the platform resources. In this case, all the advantages of HPP integration are retained, one of which is the absence of necessity for the merchant to conduct a complex and expensive PCI DSS certification.

⚠️ Currently, only acquiring payment forms with a CARD

payment method, ApplePay

and GooglePay

are supported (where card data is entered on the form itself). P2P, debit payment forms are not supported.

Payment form development #

When developing your own payment page or adapting an existing one, the following conditions must be met:

1. Technology stack – HTML / CSS / JavaScript
2. Project folder structure:

• /img
• /style
• /js
• /

3. You need to connect Checkout SDK module in the payment page code:

<script src="https://{{CHECKOUT_URL}}/sdk/pay-session.js"></script>

4. It is necessary to create a new instance of the PaySession class by passing to the constructor function the identifier of the HTML element of the form for entering data on the payment page and the parameter if on-the-fly validation of the payment form fields is needed (optional parameter). Next, call the begin() method:

<script>
    const session = new PaySession({formName: "paymentForm", validateOnInput: true});
    session.begin();
</script>

5. In the payment page HTML code, you need to link the <input> tags of the form to Checkout SDK module using special id identifiers. The module interacts only with those <input> elements that are inside the <form> tag and are indicated by the corresponding id:

<input>	Type
Payment card number	payer_card
CVV code	payer_cvv
Expiry date	payer_expiryDate
Payer name	payer_name
ZIP code	payer_zip
Payer city	payer_city
Payer phone number	payer_phone
Payer email	payer_email
Payer state	payer_state
Payer address	payer_address
Payer country	payer_country

⚠️ The form must contain at least inputs with such id: payer_card, payer_cvv, payer_expiryDate, payer_name.

6. The Checkout SDK library implements a set of methods for obtaining some session checkout parameters.

getBillingAddress() – getting the billing_address object from the merchant’s Authentication request. Object properties may be empty if the corresponding information has not been provided by the merchant. Result example:

{address: "Moore Building", city: "Los Angeles", country: "US", phone: "12345678", state: "", zip: "12345"}

getOrderInfo() – obtaining information on the current order. The function returns an object with data, for example:

{number: "111-222", amount: "10.00", currency: "USD", description: "Important gift"}

getSessionExpiry() – getting the checkout session lifetime date/time in unixtime format. Result example:

1711378966

getSessionState() – getting the current session status. Possible values: complete, redirect, waiting и decline. Example:

"decline"

getDeclinesMax() – receiving the set limit on the number of declines on the payment page. This parameter can be defined by the merchant in Authentication request and after receiving such a number of declines an automatic redirect of the user to cancelUrl will be performed.. Example of function call result:

2

getCancelUrl() – getting success_url passed by the merchant in Authentication request. Example:

"https://example.domain.com/cancel"

getCardTokens() – getting a set of available payment card tokens. The result of the call will be an array of objects, example:

[
 {
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "last": "1111",
    "month": "01",
    "year": "2025",
    "brand": "visa"
 }
]

setCardToken(token: string) – selecting a specific token for the payment process. Stored card data in the token has priority over card data from form fields.

getActiveCardToken() – getting active token, if such token was set using setCardToken function. The method returns either a string with the token or an empty value if no active token is selected. Example:

"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

clearCardToken() – to deselect the active token. This method should be used if you want to revert to the option of directly entering card data in the form fields instead of using data from the token.

getCountries() – reference function to get a complete list of countries with regions. Returns an array of objects:

[
 {
    regions: null,
    value: "AF",
    text: "Afghanistan"
  },
  {
    regions: [ {value: "ACT", text: "Australian Capital Territory"}, ... ],
    value: "AU",
    text: "Australia",
  }
]

7. Also the Checkout SDK module implements a number of event listeners, the result of which is available for processing on the form page. Event handling is optional.

onDecline – is called when the response declined is received at the time of payment processing or when checking the session state. Returns an object with the error message: {message: string}.

onSuccess – is called when the response completed is received at the time of payment processing or when checking the session status. Returns an object with successUrl: {successUrl: string}.

onFormReady – is called after getting the current session. Doesn’t return any values.

handleError – is called after an error occurs when sending a payment processing request. Returns an error object.

onInputValidation – is called when an on-the-fly validation error occurs for one of the inputs with id listed earlier (if the parameter validateOnInput: true was passed to the constructor) or as a general validation when submitting the form. Returns a validation error object: {result: string, inputId: string}.

8. To add ApplePay and GooglePay payment methods to the payment form you need to:

ApplePay

1) The container should be assigned id = applepay-container, in the body of which you need to create a div block for the button and define styles for it.

2) An event handler should be added to the button, code example:

<div id="applepay-container">
    <div class="applepay-button" onclick="handleApplePayClick()"></div>
</div>

GooglePay

1) The container should be assigned id = “googlepay-container”. Example code:

<div id="googlepay-container"></div>

2) Set the button color, the available options are “default” | “black” | “white”. Example code:

session.setGooglePayButtonColor("default")

3) Set button size, available options are “static” | “fill”. Example code:

session.setGooglePayButtonSizeMode("fill")

Further steps #

After developing the payment form, it is necessary to send the project archive, including the source code and all used files, to the manager for review, security testing and placement on the platform resources.

The payment form will be assigned a unique identifier that should be used in Checkout Authentication Request to display this payment form to customers:

{"form_id": "xxxxx-xxxxx-xxxxx"}

Example #

An example of the payment form code can be downloaded from the link