Quickstart
A simple code fragment that will help you tu unleash all the potential of Hola Cash in your e-commerce. Integrate it in minutes in the easiest way.
Checkout Widget integration demo
1. Create an account to access the Sandbox.
Create an account in our Sandbox environment, you just need an email and password to create your account. If you prefer you can use our test API Key:
Copy and paste the Test API Key and use it directly in the API Reference.
pub_sandbox_MjFiENYD.U38HsIFTKLpdiCQwOZYitzBWXgyulH6u
2. Widget customization and payment methods.
You must add the domain of the webpage in which the Widget will be displayed, you can also select the payment methods you want to include. Configure them in the Configuration > Widget customization. section.
* It's important that you only add the domain name, without the https protocol or www nor subdomains, for example, if your Widget wil be displayed inhttps://holacash.mx/widget , you just have to add holacash.mx.
3. Include Connect.js
Include this code snippet into the <head/> section of your website, replace the {PUBLIC_KEY} with your API Public Key.
The CDN_URL must be replaced depending on the environment you are using:
<script
async
id="holacash-connect"
type="text/javascript"
src="{CDN_URL}/connect.min.js"
data-public-key="{PUBLIC_KEY}"
></script>4. Include the "PAY" button element
You must include the PAY button which will show the Checkout Widget. Include this snippet where you want the button to load, replacing {PUBLIC_KEY} with your Public API Key. and {ButtonUrlBase} with the following URLs depending on environment you are using:
<div id="instant-holacash-checkout-button">
<object id="checkout-button"
data={`${ButtonUrlBase}/checkout/button?public_key=${PUBLIC_KEY}`}
data-disabled={false} />
</div>Ensure that the container div has the id instant-holacash-checkout-button and the object tag has id checkout-button
The data-disabled the attribute allows you to disable the button while the order id is fetched from the order API
We strongly suggest using the checkout button provided by the Checkout Widget. We've taken care of some basic functionality like disabling the button while you generate an order_id.
However if you want to use a custom button or to show the modal/window after an event like completing an API call, you can use the HolaCashCheckout.initiateCheckout() function. Please make sure to call this after passing an order_id inside the configure method (as described in Step 6).
5. Create an order
To be able to create a payment and initialize the Checkout Widget, first you need to create an order containing all the details from the products added to your shopping cart. Remember that the Order must be created before calling HolaCashCheckout.configure.
💡 IMPORTANT: In order for your transactions to be approved when triggering 3DS 2.0, we strongly recommend you include the Billing and Shipping information when creating the order. Please look at the API Reference documentation to create an order
For more on how to send this information, see section How to implement 3DS 2.0. on our 3DS tutorial
6. Load the Widget
When the user clicks on the button, PAY, you must initialize the Checkout Widget,passing the Order as a parameter .
HolaCashCheckout.configure(
{
order_id: order_id,
language: 'en', // 'es'
// hints are optional
hints: {
first_name: 'John',
last_name: 'Doe',
second_last_name: 'Doe',
email: 'john.doe@gmail.com',
phone: '13212312412'
},
// payments config is completely optional, but it will override the config from your Merchant portal since this settings are preferred if added in code
payments: {
credit_debit_card: {
months_without_interest: {
hide: true, // optional: hides msi installments if needed
allowed_installments: [3, 6, 9, 12, 24], // customizes displayed installments default options are (3,6,9,12)
pre_selected_installment_option: 9, // if available this option will be selected by default
},
},
bnpl: {
hide: true, //optional: hides BNPL payment method if needed,
providers: ['aplazo'] // optional: customizes displayed BNPL providers
},
},
},
callbacks
);Callbacks list:
onComplete -- > we call this callback when the charge is successfull. The Widget remains open for users. It returns the response of the charge API
onSuccess -- > we call this callback when the charge is successfull and the users click on "Finalizar" to close the Widget. Returns the response of the charge API
onAbort -- > when the user closes the Widget (modal/popup)
onError -- > when the charge fails. The parameter is the error object
onEmailEntered -- > when the user completes entering an email
onCheckoutStart -- > when the checkout page is presented
check -- > We will use the check callback to determine if Cash Pay should proceed loading the checkout page. This must return a boolean
const callbacks = {
onSuccess: (res) => {
setSuccessResponse(JSON.parse(res));
setReceiptVisible(true);
console.log("onSuccess", JSON.parse(res));
},
onComplete: (res) => {
// charge was completed correctly, but Widget remains open
// res -> contains the result from the charge API call
setReceiptDetails(JSON.parse(res));
console.log("onComplete", JSON.parse(res));
// remove comment to close Widget automatically after a charge is completed correctly
// HolaCashCheckout.closeCheckout()
},
onAbort: () => console.log("onAbort callback"),
onError: (err) => {
console.log(JSON.stringify(err));
// remove comment to close Widget automatically after a charge attempt fails
// HolaCashCheckout.closeCheckout()
},
onEmailEntered: (email) => console.log(email),
onCheckoutStart: () => console.log("checkout started"),
// this function should always return a boolean
check: () => {
return true;
},
};Pass the object callbacks as second parameter in the HolaCashCheckout.configure()
HolaCashCheckout.closeCheckout()
In order to automatically close the Widget:
- Wait to receive an onComplete or onError event.
- Call HolaCashCheckout.closeCheckout()
* Important: to avoid closing the Widget in the middle of a transaction, closeCheckout() cannot be called until one of the above mentioned events is fired.
7. Widget look and feel
This is how the Checkout Widget will look ready to process your Order and its Payment.
8. Webhook
When the payment is processed, a webhook will be sent with the information about the event. To configure the Webhook address, go to the Hola Merchant portalin the Developers section.
9. Widget Demo
In this repo you will be able to download a demo for the Widget:
Widget demo
