Skip to main content

SDK Checkout

If you prefer to use your own payment form instead of the hosted Checkout Page, the SDK lets you mount a custom form on your site and handle the payment lifecycle with JavaScript.

info

Remember to send the corresponding form_id in the authentication request so Checkout knows it should use your form.

SDK script​

<script src="https://checkout.rafinita.com/sdk/pay-session.js"></script>

Initialization​

const config = {
formName: "paymentForm", // id of the <form> in your HTML
validateOnInput: false // validate as the user types
};

const session = new PaySession(config);
session.begin();

Form structure​

The SDK detects form fields by their id. The expected fields are:

Field IDTypeDescription
payer_emailemailPayer's email
payer_ziptextPostal code
payer_phonetelPhone
payer_cardtextCard number (use inputmode="numeric", maxlength="23")
payer_expiryDatetextExpiry, MM/YY format
payer_cvvpasswordCVV
payer_nametextCardholder name
<form id="paymentForm" class="card-method-form">
<input id="payer_email" type="email" name="email" placeholder="Email" required>
<input id="payer_zip" type="text" placeholder="Zip code" required>
<input id="payer_phone" type="tel" name="phone" placeholder="Phone number" required>

<input id="payer_card" type="text" inputmode="numeric" maxlength="23" placeholder="0000 0000 0000 0000" required>
<input id="payer_expiryDate" type="text" maxlength="5" placeholder="MM/YY" required>
<input id="payer_cvv" type="password" minlength="3" maxlength="4" placeholder="CVV" required>
<input id="payer_name" required minlength="3" maxlength="22" placeholder="Full Name">

<button id="submit" type="submit">Pay</button>
<div id="googlepay-container"></div>
<div id="applepay-container">
<div class="applepay-button" onclick="handleApplePayClick()"></div>
</div>
</form>

Lifecycle events​

EventWhen it firesPayload
session.onFormReadyThe SDK finished initializing the form—
session.onSuccessThe payment succeededevent.successUrl — redirect there
session.onDeclineThe payment was declinedevent.message — message to show the user
session.onInputValidationReal-time validation of a fieldevent.inputId, event.result ("error" or valid)
session.onDecline = function (event) {
document.querySelector(".decline-message").innerText = event.message;
};

session.onSuccess = function (event) {
location.href = event.successUrl;
};

session.onFormReady = function () {
document.querySelector(".form-wrapper").classList.add("show");
};

session.onInputValidation = function (event) {
const input = document.getElementById(event.inputId);
const errorEl = document.getElementById(event.inputId + "Error");
if (event.result === "error") {
input?.classList.add("text-field--error");
errorEl?.classList.add("display-error");
} else {
input?.classList.remove("text-field--error");
errorEl?.classList.remove("display-error");
}
};

Card tokens (saved cards)​

If the customer has tokenized cards (see tokenization), the SDK exposes them like this:

const cardTokens = session.getCardTokens();
// cardTokens: [{ token, brand, last, month, year }, ...]

To use a saved token for the current payment:

session.setCardToken(token.token);

To deselect the token and re-enable the manual fields:

session.clearCardToken();

Apple Pay​

The Apple Pay button is triggered manually:

function handleApplePayClick() {
session.beginApplePay();
}

Google Pay​

The SDK injects the Google Pay button directly into the #googlepay-container element — it requires no additional logic on your side beyond having the <div> present in the DOM.