Integrating Checkout Widget
The checkout widget is a payment interface that enables you to securely collect payments from customers on your website or application. With various payment options like cards, UPI, net banking, and bank transfer (early access), it ensures a smooth checkout experience for your customers. You can also set up UPI mandates and collect recurring payments.
Follow the steps below to configure the checkout widget on your website.
1. Establish Communication
To communicate with our APIs and webhooks, you must first establish connectivity. Ensure that your setup allows or whitelists the Zoho Payments domain, payments.zoho.in.
2. Create Payment Session
To initiate the payment process, you need to create a payment session on your server. Based on your payment type, you can create the session for one-time or recurring payments.
Payment Session for One-time Payments
Call the Payment Session Create API on your server, and follow the steps below to obtain the payment_session_id.
- Collect payment information from the website (amount, currency, etc.).
- Call the Payment Session Create API using the OAuth token generated from your server.
- The API will return a
payment_session_id.
Use this payment_session_id while integrating the checkout widget.
Note:
Each session allows up to five payment attempts, but only one can be successful. Once a payment attempt is successful, no further attempts can be made within that session. Any additional attempts will result in an invalid_payment_session error. To make more payment attempts, a new session must be created.
Create Customer
Collect customer details (name, email, phone, and metadata) and call the Create Customer API using the OAuth token.
The API will return a customer_id, which you can use to initiate a payment session for mandate enrollment.
Create Payment Session for Mandate Enrollment
Call the Create Payment Session for Mandate Enrollment API on your server using an OAuth token to obtain a payment_session_id.
Note: Each session allows up to three payment attempts, but only one can succeed. Any additional attempts return an invalid_payment_session response.
Use the payment_session_id when integrating the checkout widget.
3. Integrate Checkout Widget
After receiving the payment_session_id from your server, you can invoke the checkout widget on your website. Zoho Payments' script helps you manage the payment flow easily.
- Add the Zoho Payments script given below to your website or application.
<script src="https://static.zohocdn.com/zpay/zpay-js/v1/zpayments.js"></script>
- Initialise the script using the API key generated from Zoho Payments' Developers Space.
let config = {
account_id: "23137556",
domain: "IN",
otherOptions: {
api_key:
"1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
},
};
let instance = new window.ZPayments(config);
- Invoke the
requestPaymentMethod()function withpayment_session_idto initiate the payment.
async function initiatePayment() {
try {
let options = {
amount: "100.5",
currency_code: "INR",
payments_session_id: "2000000012001",
currency_symbol: "₹",
business: "Zylker",
description: "Purchase of Zylker electronics.",
invoice_number: "INV-12345",
reference_number: "REF-12345",
address: {
name: "Canon",
email: "canonbolt@zylker.com",
phone: "98XXXXXXXX",
},
};
let data = await instance.requestPaymentMethod(options);
} catch (err) {
if (err.code != "widget_closed") {
// Handle Error
}
} finally {
await instance.close();
}
}
initiatePayment();
Once the checkout widget is integrated, you can collect payments, gather transaction details such as amount, currency, and customer information, and verify the payment status. You verify the payment status using the payment_id provided after the user completes the payment.
4. Confirm Payment
Once the customer completes the payment, you can confirm the payment using the requestPaymentMethod() function. This function returns a response that includes the payment_id, and for recurring payments, both the payment_id and mandate_id.
These IDs can be used to track the payment and mandate status. If a payment fails due to issues like payment errors or user cancellations, refer to the error messages to identify and resolve the issue.
5. Verify Payment Status
After receiving the payment_id, verify the payment status using the Payment Retrieve API. For recurring payments, use the Retrieve Mandate API to check specific mandates. Based on the status returned (success, failure, or pending), update your system.
Alternatively, you can configure webhooks to receive the events payment.success and payment.failed to receive the final payment status update to your server directly.
Walkthrough of Zoho Payments personalized to your business needs