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.
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 ID | Type | Description |
|---|---|---|
payer_email | email | Payer's email |
payer_zip | text | Postal code |
payer_phone | tel | Phone |
payer_card | text | Card number (use inputmode="numeric", maxlength="23") |
payer_expiryDate | text | Expiry, MM/YY format |
payer_cvv | password | CVV |
payer_name | text | Cardholder 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
| Event | When it fires | Payload |
|---|---|---|
session.onFormReady | The SDK finished initializing the form | — |
session.onSuccess | The payment succeeded | event.successUrl — redirect there |
session.onDecline | The payment was declined | event.message — message to show the user |
session.onInputValidation | Real-time validation of a field | event.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.