Skip to content
Process Payments/
/
Initial Setup
Last updated

Initial Setup

Overview

The embedded SDK requires some initialisation before it can be used to process payments. The minimal initialisation consists of the following fields:

  • clientSecret: This is the secret key returned when creating a Payment Session, although it could also be passed later when attempting the payment (see here).
  • publicKey: This is the public key which is used to authenticate the SDK and is available in the Ryft Portal.
  • accountId: This is the unique identifier for the Sub-Account, provided the Payment Session is set-up using the Platform Fee model.

In the next sections on this page, you will learn how to set up a basic payment form using the embedded SDK.

The following guide demonstrates the process using the JavaScript Web SDK. However, the same features and functionalities are available across all other SDKs, unless otherwise specified.

Initialisation

To get started, include the following script tag in your HTML file to load the embedded SDK:

Ryft JS SDK tag
<script src="https://embedded.ryftpay.com/v2/ryft.min.js"></script>

Then, create a basic HTML structure for the payment form, including a PAY button to submit the payment request and a section to display any potential errors:

Basic Payment Form
<!DOCTYPE html>
<html lang="en">

<head>
    <script src="https://embedded.ryftpay.com/v2/ryft.min.js"></script>
</head>

<body>
    <div>
        <div class="Ryft--paysection">
            <form id="ryft-pay-form" class="Ryft--payform">
                <button id="pay-btn">PAY NOW</button>
                <div id="ryft-pay-error">
                </div>
            </form>
        </div>
    </div>
</body>

Now, you can initialise the SDK as follows according to your payment model:

Single Payment & Split Payment - Basic SDK Initialisation
const publicKey = "pk_XXXXXXX"; // Available in the Ryft Portal
const clientSecret = "ps_XXXXXXX"; // Returned when creating a Payment Session

Ryft.init({
    publicKey,
    clientSecret
});

Next step is to handle the payment submission.

Submitting the Payment

Once the form is initialised, you can handle the form submission to process the payment when the user clicks the PAY button.

This is done by adding an event listener to the PAY button via the Ryft.attemptPayment method. Here’s an example of how to do this:

Handling the PAY button click event
const payButton = document.getElementById("pay-btn");

payButton.addEventListener("click", async (e) => {
    e.preventDefault();

    try {
        const paymentSession = await Ryft.attemptPayment(attemptPaymentRequest);
        handlePaymentResult(paymentSession); // Handle the result (see next section)
    } catch (error) {
        // Show error to customer
    }
});

The Ryft.attemptPayment method will handle the payment submission and return a promise that resolves when the payment is complete or rejects if there was an error.

You can then handle the result accordingly, such as showing a success message or displaying an error to the customer.

Handling the Result

The result of the payment attempt can be handled in the promise returned by the Ryft.attemptPayment method. Here’s an example of how to do this:

Handling the payment result
function handlePaymentResult(paymentSession) {
    if (
        paymentSession.status === "Approved" ||
        paymentSession.status === "Captured"
    ) {
        // Payment successful – show success page
        console.log("Payment Successful", paymentSession);
        document.getElementById("ryft-pay-error").innerHTML = "<p style='color: green;'>Payment Successful!</p>";
        return;
    }
    if (paymentSession.lastError) {
        // Show error to customer
        const userFacingError = Ryft.getUserFacingErrorMessage(
            paymentSession.lastError
        );
        console.error("Payment Error", paymentSession.lastError, userFacingError);
        document.getElementById("ryft-pay-error").innerHTML = `<p style='color: red;'>${userFacingError}</p>`;
    }
}

The example above checks the status of the paymentSession returned by the Ryft.attemptPayment method:

  • If the status is Approved or Captured, it indicates that the payment was successful, and you can show a success page to the customer.
  • If there is a lastError, you can use the Ryft.getUserFacingErrorMessage method to get a user-friendly error message to display to the customer and log the error for debugging purposes as shown in the example below.

Putting It All Together

Here's a complete basic example that combines all the steps above:

Complete Basic Payment Form Example
<!DOCTYPE html>
<html lang="en">

<head>
    <script src="https://embedded.ryftpay.com/v2/ryft.min.js"></script>
</head>

<body>
    <div>
        <div class="Ryft--paysection">
            <form id="ryft-pay-form" class="Ryft--payform">
                <button id="pay-btn">PAY NOW</button>
                <div id="ryft-pay-error">
                </div>
            </form>
        </div>
    </div>
</body>

<script type="text/javascript">
    const clientSecret = ""; // Returned when creating a Payment Session
    const publicKey = ""; // Available in the Ryft Portal
    const accountId = ""; // The unique identifier for the Sub-Account, if using Platform Fee model

    Ryft.init({
        publicKey,
        clientSecret,
        // accountId: accountId, // Uncomment if using Platform Fee model
    });

    // Get a reference to the pay button
    const payButton = document.getElementById("pay-btn");

    function handlePaymentResult(paymentSession) {
        if (
            paymentSession.status === "Approved" ||
            paymentSession.status === "Captured"
        ) {
            console.log("Payment Successful", paymentSession);
            document.getElementById("ryft-pay-error").innerHTML =
                "<p style='color: green;'>Payment Successful!</p>";
            return;
        }

        if (paymentSession.lastError) {
            const userFacingError = Ryft.getUserFacingErrorMessage(
                paymentSession.lastError
            );
            console.error("Payment Error", paymentSession.lastError, userFacingError);
            document.getElementById("ryft-pay-error").innerHTML = `<p style='color: red;'>${userFacingError}</p>`;
        }
    }

    // Add event listener to the PAY button
    payButton.addEventListener("click", async (e) => {
        e.preventDefault();

        try {
            const paymentSession = await Ryft.attemptPayment();
            handlePaymentResult(paymentSession);
        } catch (error) {
            // Show error to customer
            console.error("Payment Error", error);
            document.getElementById("ryft-pay-error").innerHTML =
                "<p style='color: red;'>An unexpected error occurred.</p>";
        }
    });
</script>

</html>

When you open this HTML file in a browser, it will display a simple card payment form with a PAY button.

When the button is clicked, it will attempt to process the payment using the embedded SDK and handle the result accordingly.

Make sure to replace the placeholder values for clientSecret, publicKey, and accountId with actual values from your Ryft account and Payment Session.

Please note, after clicking the PAY button, the payment may take a few seconds to process. During this time, you may want to disable the PAY button to prevent multiple submissions and provide feedback to the user that the payment is being processed. Please refer to the SDK Events section for more details on how to handle such scenarios.

Next Steps

You should now have a basic payment form set up and be able to process card payments using the embedded SDK.

You can further enhance your integration by handling SDK events to improve the user experience. For more information, refer to the SDK Events page.

Previous page
Next page