# Additional Configurations ## 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](/documentation/get_started/initiate_payments/additional_settings#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: ```javascript Zero-Value Authentication Example 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: ```javascript Manual Required Actions Handling Example 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](/documentation/get_started/process_payments/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: ```javascript Handle Required Actions Example 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: ```javascript Handle Required Actions Server-to-Server Example 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: ```javascript Passing Additional Data Example 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: ```javascript Custom Localisation Example 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: ```javascript Custom Styles Example Ryft.init({ publicKey, clientSecret, style: { borderRadius: 2, backgroundColor: "#000", borderColor: "#000", padding: 10, color: "#FFF", focusColor: "#FFF", bodyColor: "#000", }, }); ``` Please note that the embedded SDK includes "ryft-" prefixes in its CSS classes to avoid conflicts with other styles on your webpage. When applying custom styles, ensure that you target the appropriate classes with the "ryft-" prefix.