Full SDK
Below, we outline the step-by-step process to enable the full SDK functionalities in your system:
Step 1: Include the library in your project.
Ensure the Yuno SDK file is included in your webpage before closing the tag. Refer to the example below:
<script src="https://sdk-web.y.uno/v1/static/js/main.min.js"></script>
Step 2: Initialize SDK with the public key
In your JavaScript application, create an instance of the Yuno
class by providing a valid PUBLIC_API_KEY. Check the Get your API credentials guide.
Like the example below, use the initialized class that is attributed to the yuno
constant.
const yuno = Yuno.initialize(PUBLIC_API_KEY)
Step 3: Start the checkout process
You will start the checkout process. To do it, use the function yuno.startCheckout
and provide the necessary parameters.
The following table lists all required parameters and their descriptions. For optional parameters go to Complementary Features.
Parameter | Description |
---|---|
checkoutSession | Refers to the current payment's checkout session.Example: '438413b7-4921-41e4-b8f3-28a5a0141638' |
elementSelector | Specifies the HTML element where you want to mount the Yuno SDK. The SDK will be rendered within this element. |
countryCode | This parameter determines the country for which the payment process is being configured. It should be set to one of the following country codes: CO, BR, CL, PE, EC, UR, or MX. |
language | Defines the language to be used in the payment forms. You can set it to one of the available language options: es (Spanish), en (English), or pt (Portuguese). |
onLoading | Required to receive notifications about server calls or loading events during the payment process. |
yuno.startCheckout({
checkoutSession: '438413b7-4921-41e4-b8f3-28a5a0141638',
elementSelector: '#root',
countryCode: 'CO',
language: 'es',
onLoading: (args) => {
console.log(args);
}
async yunoCreatePayment(oneTimeToken) {
await createPayment({ oneTimeToken, checkoutSession })
yuno.continuePayment()
},
})
Step 4: Mount the SDK
Display the payment methods by using the function yuno.mountCheckout()
by selecting an HTML element and using a valid CSS selector (#
, .
, [data-*]
)
/**
* Mount checkout in browser DOM
*/
yuno.mountCheckout()
If you want to set a default payment method, use the following code to mount it:
/**
* Mount checkout in browser DOM with a payment method selected by default
* @optional
*/
yuno.mountCheckout({
/**
* Optional, only needed if you would like this method type selected by default
* Can be one of 'BANCOLOMBIA_TRANSFER' | 'PIX' | 'ADDI' | 'NU_PAY' | 'MERCADO_PAGO_CHECKOUT_PRO
*/
paymentMethodType: PAYMENT_METHOD_TYPE,
/**
* Optional
* Vaulted token related to payment method type
*/
vaultedToken: VAULTED_TOKEN,
})
Step 5: Initiate the payment process
After the user has selected a payment method remember to call yuno.startPayment()
to initiate the payment flow. Below you will find an example where yuno.startPayment()
is called when the user clicks on button-pay
:
const PayButton = document.querySelector('#button-pay')
PayButton.addEventListener('click', () => {
yuno.startPayment()
})
Step 6: Get the OTT (One Time Token)
Once the customer fills out the requested data in Yuno's payment forms, the SDK provides the OTT. The configuration function yuno.CreatePayment(oneTimeToken)
is then triggered with the OTT (One Time Token).
yunoCreatePayment(oneTimeToken)
You can also use tokenWithInformation to receive any additional info given by the customer in the checkout such as installments or document type/number.
yunoCreatePayment(oneTimeToken, tokenWithInformation)
Important
The merchant is responsible for handling the loader. Yuno offers an option to use our loader; however, the merchant can use their own loader and must make the corresponding configurations.
Step 7: Create the Payment
Once you have completed the steps described before, you can create a payment. The back-to-back payment creation must be carried out using the Create Payment endpoint. The merchant should call their backend to create the payment within Yuno, using the OTT (One Time Token) and the checkout session.
- Continue: We recommend integrating the method
continuePayment
of the SDK after the payment is created because certain asynchronous payment methods require additional action from the customer to complete it. The API will inform you of this scenario via the fieldsdk_action_required
of the response, which will be returned as true. The functionyuno.continuePayment()
will display the additional screens to the customers, where they can carry out the necessary actions to complete the payment. Otherwise, this step is not necessary.
After this step, you can complete the end-to-end integration by referencing back to the Step by Step integration of the Full SDK
Complementary Features
In addition to the code examples provided, you can access the Demo App for a complete implementation of Yuno SDKs or go directly to the HTML and JavaScript checkout demos available on GitHub.
Yuno Web SDK provides additional services and configurations you can use to improve customers' experience:
- Form loader
- Render mode
- Card form configurations
- Bank Issuer List
- SDK Customizations: Change the SDK appearance to match your brand.
- Payment Status: Update the user about the payment process.
- 3DS Setup SDK: Integrate 3DS into your payment flow.
Parameter | Description |
---|---|
keepLoader | You can choose whether to hide or show the Yuno loading/spinner page. Enabling this option ensures that the loading component remains displayed until either the hideLoader() or continuePayment() function is called. The default value is true. |
yuno.startCheckout({
showLoading: true,
})
Parameter | Description |
---|---|
issuersFormEnable | Through this parameter, you can configure the SDK to enable the issuer's form (bank list) |
yuno.startCheckout({
issuersFormEnable: true,
})
Parameter | Description |
---|---|
renderMode | Determine the mode in which the payment forms will be displayed. - type : can be one of modal or element .- elementSelector : Element where the form will be rendered* Only needed if type is element . |
yuno.startCheckout({
renderMode: {
type: 'modal',
elementSelector: '#form-element',
},
})
Parameter | Description |
---|---|
card | Define specific settings for the credit card form - type : step o extends - styles : You can edit card form styles. Only you should write css, then it will be injected into the iframe.- cardSaveEnable : Show checkbox for save/enroll card. Default value is false.- texts : Custom texts in Card forms buttons. |
yuno.startCheckout({
card: {
type: "extends",
styles: '',
cardSaveEnable: false,
texts: {}
},
})
Save card for future payments:
In addition, you can display a checkbox for save or enroll cards using cardSaveEnable: true
. Below you can find examples of the checkbox for both card form renders.
Rendering modes
Below you find screenshots presenting the difference between the:
- Render modes
modal
andelements
for the payment method list. - Render modes
step
andextends
for the credit card form.
- You also can choose one of the render options for the card form,
step
andextends
:
Text payment form buttons
Parameter | Description |
---|---|
texts | Provide custom text for payment form buttons to match your application's language or branding. |
yuno.startCheckout({
texts: {
customerForm?: {
submitButton?: string;
}
paymentOtp?: {
sendOtpButton?: string;
}
}
})
External Payment Buttons
Parameter | Description |
---|---|
externalPaymentButtons | Configure external payment buttons, such as Paypal, Google Pay, or Apple Pay. |
yuno.startCheckout({
externalPaymentButtons: {
paypal: {
elementSelector: '#paypal',
},
},
})
Persist credit card form to retry payments
In case a a transaction is rejected, you can persist the credit card form to retry a payment after the customer has entered the credit card details. In order to do that, you will need to:
- Add the following parameter while initializing the SDK to persist the credit card form after the one time use token is created:
yuno.startCheckout({ automaticallyUnmount: false, })
- In case the transaction is rejected, you will need to:
- Execute the method
yuno.notifyError()
to delete the previously entered CVV for the first transaction. - Create a new checkout session and update the SDK with the new one by executing
yuno.updateCheckoutSession(checkoutsession)
- Execute the method
- Continue with the new checkout and one time use token with the regular payment flow.
Updated about 1 month ago