Additional Configurations

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Zero-Value Authentications

In certain scenarios, you may want to perform a zero-value authentication to verify a customer's payment method without actually charging them. This is often used for validating card details or setting up a payment method for future use.

To perform a zero-value authentication, you first need to create a Payment Session set for this purpose. You can find more details on how to do this in the Account Verification section.

Once a Payment Session for zero-value authentication has been created and you have the clientSecret, you can initialize the embedded SDK with the appropriate configuration. Specifically, you need to set the usage option to "setupCard" when initializing the SDK.

Here's an example of how to configure the embedded SDK for zero-value authentication:

Ryft.init({
    publicKey,
    clientSecret,
    usage: 'setupCard'
});

If the zero-value authentication is successful, the customer will not be charged, but the payment method will be validated and can be used for future transactions.

Required Actions

By default, the embedded SDK handles most payment flows seamlessly before the result is returned to your application. However, in certain scenarios you may want to handle specific actions in a manual way.

Configuring the SDK

To configure how the embedded SDK handles required actions, you can use the manuallyHandleActions configuration flag when initializing the SDK. When set to true, this flag allows you to manage required actions manually, giving you more control over the payment process.

Here's an example of how to configure the embedded SDK to manually handle required actions:

Ryft.init({
    publicKey,
    clientSecret,
    manuallyHandleActions: true, // Enable manual handling of required actions
});

Handling Required Actions

When manuallyHandleActions is set to true, or the payment is processed using the Server-to-Server approach, if the payment requires any additional actions (such as 3D Secure authentication), then this must be handled accordingly.

The embedded SDK will provide a requiredAction object in the response after attempting to process the payment. You can then use this object to finalise the required action using the Ryft.handleRequiredAction() method.

Here's an example of how to handle required actions manually:

if (paymentSession.requiredAction) {
    Ryft.handleRequiredAction(paymentSession)
        .then((updatedPaymentSession) => {
            if (
                updatedPaymentSession.status === "Approved" ||
                updatedPaymentSession.status === "Captured"
            ) {
                // Payment successful - show the customer your order success page
                return;
            }
            if (paymentSession.lastError) {
                const userFacingError = Ryft.getUserFacingErrorMessage(
                    paymentSession.lastError
                );
                // Show userFacingError to customer
            }
        })
        .catch((error) => {
            // Show error to customer
        });
}

Please note, when using the Server-to-Server approach, you will have the requiredAction object returned in the response from your server after attempting to process the payment. You can then pass this object to the Ryft.handleRequiredAction() method as follows:

const requiredAction = { // Replace with your actual requiredAction object (copy-paste from the API response)
    "type": "Identify",
    "identify": {
        "threeDsMethodUrl": "https://xxxxxxxxxxxxxxxxxx",
        "threeDsMethodData": "abcd1234abcd1234",
        "scheme": "XXXX",
        "paymentMethodId": "pmt_XXXXXXXXXXXXXXXX",
    },
};

form.addEventListener("submit", async (e) => {
    e.preventDefault();

    Ryft.handleRequiredAction(requiredAction, publicKey, clientSecret)
        .then((paymentSession) => {
            handlePaymentResult(paymentSession);
        })
        .catch((error) => {
            // Show error to customer
        });
});

Passing Additional Data

In some cases, you may want to pass some required information to the embedded SDK that is not collected at previous stages of the SDK initialisation.

This can include:

• Client Secret: if this was not available at the time of initialising the SDK;
• Customer Email: if this was not available at the time of creating the Payment Session. The customerEmail or customerDetails.id is required for processing the payment. If it was not provided at the time of creating the Payment Session, then it must be provided here.

Here's an example of how to pass additional data to the embedded SDK:

const form = document.getElementById("ryft-pay-form");

form.addEventListener("submit", async (e) => {
    e.preventDefault();

    const attemptPaymentRequest = {
        clientSecret: "ps_XXXXXXXXXXXXXXXX", // The payment session client secret
        customerEmail: "test@email.com", // The customer's email address
    };

    try {
        const paymentSession = await Ryft.attemptPayment(attemptPaymentRequest);
        // Handle successful payment attempt here
    } catch (error) {
        // Show error to customer
    }
});

The example above demonstrates how to pass the clientSecret and customerEmail to the embedded SDK when attempting to process a payment. This is particularly useful if this information was not available during the initial SDK setup or Payment Session creation.

Customising the Form

The embedded SDK provides some customisation options to tailor the appearance and behaviour of the embedded payment form to better fit your application's design and user experience requirements.

Localisation

The embedded SDK supports localisation, allowing you to display the payment form in different languages based on your customer's preferences or location.

Here are the SDK properties that can be used to configure localisation:

• cardNumberPlaceholder: Custom placeholder text for the card number input field. Defaults to "Card number".
• expiryMonthPlaceholder: Custom placeholder text for the expiry month input field. Defaults to "MM".
• expiryYearPlaceholder: Custom placeholder text for the expiry year input field. Defaults to "YY".
• cvvPlaceholder: Custom placeholder text for the CVC input field. Defaults to "CVC".
• nameOnCardPlaceholder: Custom placeholder text for the name on card input field. Defaults to "Name on card".

Here's an example of how to configure the embedded SDK with custom localisation options:

Ryft.init({
    publicKey,
    clientSecret,
    localisation: {
        cardNumberPlaceholder: "1234 5678 9012 3456",
        expiryMonthPlaceholder: "mm",
        expiryYearPlaceholder: "yy",
        cvvPlaceholder: "123",
        nameOnCardPlaceholder: "Name as it appears on your card",
    },
});

Custom Styles

The embedded SDK allows you to apply custom styles to the embedded payment form to match your application's branding and design guidelines. You can customize various aspects of the form's appearance, including colors, fonts, and layout.

To apply custom styles, you can use the styles configuration option when initializing the embedded SDK. This option accepts an object where you can define CSS properties for different elements of the form.

Here are the elements that can be styled:

• borderRadius: The radius of the card form borders. Defaults to 4 (px).
• backgroundColor: The background color inside the card form. Defaults to #FFF (white).
• borderColor: The border color of the card form when not focused. Defaults to #838383 (grey).
• padding: The padding inside the card form. Defaults to 12 (px).
• color: The text color inside the card form. Defaults to #FFF (white).
• focusColor: The border color of the card form when focused. Defaults to #FFF (white).
• bodyColor: The body's colour within the iframe. Defaults to #000 (black).

Here's an example of how to configure the embedded SDK with custom styles:

Ryft.init({
    publicKey,
    clientSecret,
    style: {
        borderRadius: 2,
        backgroundColor: "#000",
        borderColor: "#000",
        padding: 10,
        color: "#FFF",
        focusColor: "#FFF",
        bodyColor: "#000",
    },
});