On this page

• Before you begin
• Setting up ZEN checkout
• Creating a request
• Generating a signature
• Payments setup
• Instant Payment Notification
• Hash calculation
• Testing payments
• Testing refund payments
• Locating transactions in ZEN account
• Finding settlements
• PayPal 
• Widget
• Specified Payment Channel

ZEN checkout integration

ZEN allows direct checkout integration without a complex API implementation through ZEN checkout integration.

With ZEN checkout integration, the process only requires communication that initiates a paywall hosted on the ZEN side.

If you cannot find the e-commerce platform your store is powered by in our /plugin list/, or your e-commerce platform does not support complex API integration, then this method may be right for you.

 

Before you begin

• Log in to your ZEN panel, open the menu and go to Store settings > Payment methods.
• Now, select payment methods which you would like to enable on your checkout page.
  Note: For a multiple-terminal setup, please make sure to select the desired terminal from the dropdown list.
• Next, locate your integration credentials. See how to get integration credentials.
• Then, create a working POST request. See more in the POST checkout part.
• Finally, correctly receive an IPN from ZEN. 

 

Setting up ZEN checkout

To set up ZEN checkout, you should POST proper form data to this ZEN URL address: https://secure.zen.com/api/checkouts

The below table provides the full description of the form data fields.

* Customer information (firstName, lastName, email) can be omit during transaction initiation.
In such cases, checkout, during transaction process, will create a pop-up requesting customer to provide those information.
Y – required; N – No required

  

  

Limiting checkout to desired payment method or payment channel

You can limit your checkout to particular payment method or payment channel.
By providing one of „specifiedPaymentMethod” or „specifiedPaymentChannel” you can prevent your buyers from using other methods in payment session.

You can either initiate the checkout with chosen method or chosen channel.
Examples:
„specifiedPaymentMethod”: „PME_BOACOMPRA” – will limit checkout to all channels under BOACOMPRA payment method.
vs
„specifiedPaymentChannel”:” PCL_BOACOMPRA_PAGOEFECTIVO”- this will limit checkout to only one channel from BOACCOMPRA payment method.

To get information about available payment methods codes and payment channels codes please contact us at [email protected] and provide us with your terminal ID

 

Request to initiate checkout should be prepared as JSON and send with application/json header.

Example of JSON:

 

Generating a signature

A signature is created based on the JSON prepared for the request, using one of SHA224/SHA256/SHA284/SHA512 algorithms

To generate signature, following actions should be applied:

Below, you can find an example of signature generation process:

 

Payments setup

Payment methods

To learn all about payment methods available in ZEN, check the Payments section in the ZEN Features chapter.

Enabling payment methods

You can find all available payment methods in your ZEN panel in the Store settings option. You can turn them ON and OFF at any time according to your preferences. The methods which logos are colorful are the ones enabled. On the checkout page, your customers will only see the methods which are turned ON. 

Instant Payment Notification

Instant Payment Notification (IPN) is a mechanism that informs your system about payment statuses, outcomes of actions such as refunds, and the reception of results for certain local payment methods and other events.

Key advantages of IPN:

1. Automatic event updates: IPN automatically updates events triggered by requests from your end. For example, when a customer initiates a refund or when an up-to-date sales report is required.
2. Asynchronous request processing: In the case of IPN, requests are processed asynchronously. For many payment methods, the waiting time for a response may be longer, but with IPN notification of a successfully completed payment, you receive automatic information.

To handle IPN, you need to:

1. Provide an endpoint on your server: You must provide an endpoint that will receive and process IPN POST from ZEN. Depending on your network requirements and security, it may be necessary to add our IP address to the whitelist on your firewall.
2. Configure IPN: Set up IPN to specify which events should be monitored and transmitted to your system. You can configure this in two ways, following the documentation.

For each finalized transaction, ZEN sends you an IPN. There are two ways to provide the IPN URL to ZEN:

1. In the Credentials tab in the Merchant panel, you can provide the IPN URL address.
2. If you are using API Integration or Paywall Integration with each request, you can provide a customIpnUrl for this request as an optional field. If you leave this field blank, ZEN will use the IPN URL address from point 1. To verify whether the IPN is sent by ZEN, you should use the IPN API Secret. Note: You should create a hash for particular values using sha256 and compare the result with the hashed values of the received IPN.

1. To verify whether the IPN is sent by ZEN, you should use the IPN API Secret. See how to get integration credentials.
   Note: You should use hash for particular values using sha256 and compare the result with the hashed values of the received IPN.

Below, you can find an example of an IPN

Merchant Secret used for this example is:

with

we get

which gives 

The received hash is equal to the hash received in IPN. This confirms that IPN was sent by ZEN.

To confirm that the IPN was successfully received, your system must send the following response

-content type: application/json

Response:

Note: If you don’t confirm that the IPN has been received, ZEN will continue to re-send IPN to your URL address.

 

Hash calculation

Hash values are calculated as follows:

 

Testing payments

When you have completed all the previous steps, you can carry out a test payment.

•  Create an order at your store and follow through with all the steps.
• Upon payment completion, our system should display a success message at the end of the checkout.
• Check for the new transaction in your ZEN panel.

 

Testing refund payments

Transactions processed via ZEN can be partially or fully refunded to the payer.

Refunds can be processed in two ways: in the ZEN panel or via API.

Processing refunds in the ZEN panel

• Log in to your ZEN panel, open the menu and select the Payments section.
• Locate the transaction which you would like to refund and display its details.
• Click on the Refund button, and specify the amount to be refunded.

 The refunded amount cannot be lower than the min. transaction value, nor greater than the amount of refunded transaction.

API

• Prepare the POST /transactions/refund according to our API documentation.
• The refunded amount cannot be lower than the min. transaction value, nor greater than the amount of refunded transaction.

transactionId – id of the transaction to be refunded provided by ZEN
merchantTransactionId – id of the refund transaction from your system. It must be unique (no 2 transactions, no matter the type, can have same merchantTransactionId

 

Locating transactions in ZEN account

You can display, search and filter all transactions processed with ZEN in your ZEN merchant panel.

 To do this, go to your ZEN panel and select the Payments section from the menu. 

 You can also create a detailed report of all transactions made in a specified period. To learn how to do this, read the Reports chapter.

Finding settlements

Each transaction in your store is settled to your ZEN IBAN account (unless specified otherwise in the contract or T&C of your payment processor, e.g. PayPal).

The settlement time depends on the settlement delay and the security deposit values per payment method. ZEN specifies settlement delay and security deposit periods in your contract, T&C, and an email confirming the activation of your store in ZEN.

You can find all the settlements for specified currencies in your ZEN account’s transaction history.

PayPal 

You can connect your PayPal account with ZEN to enable your customers to pay and process their payments through PayPal.

Please note that the settlement and pricing terms must be agreed upon between PayPal and you. ZEN does not participate in either of those processes and only enables redirecting payers to the PayPal checkout page.

To process PayPal transactions:

• First, log in to your ZEN panel.
• From the menu, select Store settings and then click on the black-and-white PayPal logotype.
• The PayPal login popup will appear on the screen. Log in or create a new account to connect your PayPal account with ZEN and follow the account connection steps.
• Once PayPal and ZEN accounts have been connected you can:
  • process PayPal transactions via API according to the API integration chapter.
  • enable PayPal on your ZEN checkout as presented in the Enabling payments section of the API integration chapter.

Widget

Widget is an additional feature available in ZEN designed exclusively for processing card transactions. This widget offers several advantages, including:

This additional module is intended for integration with the checkout process. Invoking the widget is not significantly different from initiating a standard payment transaction during the checkout process. However, you need to include the „specifiedPaymentChannel” parameter in the request content, which must always be declared as „PCL_CARD”. To initiate a transaction using the widget, the merchant should use the following URL instead of the standard URL for initiating transactions:  https://secure.zen.com/api/checkouts/type=widget In response to the request, instead of a redirection URL, you will receive an „Id” identifier, which should be used instead of „checkoutId” in the „openPopup(„checkoutId”);” function in the code that you took after customizing the widget according to your needs. The „Id” is a unique value generated for each registered transaction, which will be processed by the widget to finalize the transaction. This value serves to clearly identify and conclude the transaction process.

In summary, the ZEN platform widget is a tool that facilitates card payments, providing a personalized appearance, data security, and support for various transaction outcomes, all without the need to redirect the customer to an external payment page.

Specified Payment Channel

The „specifiedPaymentChannel” parameter is a crucial element that enables us to:

• Initiate transactions using a specific designated payment method when a partner chooses to offer only that particular payment option to their customers or when the partner wants only that payment option to be visible at checkout.
• Initiate card transactions using a widget.

To properly use the parameter: During payment initiation, instead of the standard „PaymentChannel” parameter, we use „specifiedPaymentChannel” to declare the preferred payment channel visible in the checkout payment process. This allows us to precisely specify the preferred payment method for a given transaction.

Below, you can find an example how use that parameter: