API integration

Before you begin

1. First, prepare all the credentials for this integration. See how to get the credentials. 
2. Next, get a list of all available payment methods. See the list of payment methods.
3. Keep in mind that each purchase and refund are followed by an IPN. Learn more about IPN.
4. For security reasons, you must have a fraud collector installed on your checkout page. See how to install a fraud collector.

See the complete API documentation.

GET /terminals

In the API integration, you can process two types of transactions:

• purchase (TRT_PURCHASE)
• refunds (TRT_REFUND)

Learn more about payments.

Calling the GET /terminals endpoint will return the list of all available methods for the requested terminal. 

Note: Applying changes in store settings does not impact the list of payment methods displayed by GET /terminals.

Enabling payments

See more in the API documentation.

The get /terminals request returns all available methods.

Applying changes in Store settings does not have an impact on the list of payment methods displayed by get /terminals

Payment methods

In the below table, you can find all payment methods available for configuration through API.

Fraud collector

Note: This feature is only supported for API Integration.

The Fraud collector allows you to obtain fingerPrintId which is crucial for processing transactions in API Integration. Obtained values should be sent to ZEN with each purchase request.

To install javascript in your checkout, follow the instructions.

Creating a fingerPrintId

To create fingerPrintId, you should implement following code into your website or app.

Code:

Then, send the retrieved fingerprint (“data” from console.log within seon.getBase64Session function) value to ZEN.

POST /transactions in fraudFields.fingerPrintId

Saving and tokenizing cards

Note: This feature is only supported for API Integration.

You can save card data in the form of a token and use it for future transactions instead of asking the user to fill in card details each time they make a transaction.

Create a new transaction using POST /transaction. See more in the API documentation.

In the 'paymentSpecificaData' object, send all data according to the API documentation and make sure that:

purchase

authorization (once payment is authorized, ZEN will instantly cancel it and provide money back to the payer)

In return, ZEN will generate a unique token associated with this card which will be saved in the store.

Location of the token in response: cardInfo.token

The card data are saved for the user as provided in the POST /transactions request: customer.id. This identifier will be used to manage saved/tokenized card data.

Tokenized cards are saved in 'PAYMENT PROFILES'. Learn more in the API documentation.

You can carry out the following actions with all saved card tokens:

• Request a list of all saved cards (for provided external-customer-id, as described in the Saving and tokenizing cards section)
• Request data of a particular saved card (for provided card id, obtained in point 1)
• Update data of a particular saved card (for provided card id, obtained in point 1)
• Delete a previously saved card (for provided card if, obtained in point 1)

Oneclick payments

Note: This feature is only supported in API Integration.

Oneclick feature allows merchants to initiate card payment without a need for the payer to input card data. Instead, previously saved card tokens are being used.

1. Enable saving and tokenizing cards
2. Initialize payments with a saved tokenized card:
   1. First, create a new transaction using POST /transaction. See more in the API documentation.
   2. In the 'paymentSpecificaData' object, send all data according to the API documentation. while making sure that:

cardToken - contains the token data you've received in Step 1
type - is set to one click

Apple Pay

This technical guide describes how to connect Apple Pay with your ZEN API Integration. For more information on Apple Pay please check the Apple Pay documentation.

Before you begin (important)

Before you start the integration process, you must first go through the registration process. For more information, see the following links:

• Relevant Guidelines
• Regional Regulations guidelines
• Apple Developer Program Account registration
• Apple Merchant ID creation
• Domain validation

Creating certificates

To create a Payment Processing Certificate, please contact us for the Certificate Signing Request with the following information:

• your Apple Merchant ID
• email address of your ZEN business account
• your ZEN Shop ID in the message.

The Certificate Signing Request is used to create a Payment Processing Certificate. The full process is described in the Apple help guide.

Once you have received the Payment Processing Certificate, please provide it back to ZEN. See how to contact us.

See also: Apple Merchant Identity Certificate guidelines

Integration with Apple

To integrate your e-store or iOs app with Apple Pay, please check the below knowledge sources:

• For important information, see the Apple guide on implementing Apple Pay on websites. 
• Check whether the device or browser supports Apple Pay in the Apple Pay availability guide. 
• Learn more about Apple payment requests.

IMPORTANT

• ZEN only accepts Visa and Mastercard®. Make sure to whitelist only those two networks in the Supported networks section:
  
  supportedNetworks=""<?=[CardForm::CARD_ORGANISATION_MASTERCARD, CardForm::CARD_ORGANISATION_VISA]?>""
• Display the payment button and payment sheet.

See also: Offering Apple Pay in your App

When you have followed all of the above instructions, you can POST the payment to ZEN as described in the API documentation.

Make sure to create transactions as:

Google Pay™

This technical guide describes how to connect Google PAYwith your ZEN API .

For more information, please check the Google Pay™ documentation.

Before you begin (important)

Before you start the integration process, please see the below knowledge sources:

• Registrations: Google Pay for web payments documentation: 

https://developers.google.com/pay/api/web/overview?hl=en&authuser=2

https://developers.google.com/pay/api/android/overview?authuser=2

• Terms, conditions and guidelines:

https://payments.developers.google.com/terms/sellertos

https://payments.developers.google.com/terms/aup

https://developers.google.com/pay/api/web/guides/brand-guidelines?authuser=2

https://developers.google.com/pay/api/android/guides/brand-guidelines?authuser=2

See also: Setup your website and Google Account for Google Pay. 

Integrating your website store with Google Pay

To integrate your website with Google Pay:

1. Follow the tutorial described in Google Pay documentation.
2. Review your integration and fill Google Pay integration checklist.
3. Request production access.
4. Setup your website and launch your integration.
5. Test Google Pay with ZEN on your website.

IMPORTANT

ZEN only accepts Visa and Mastercard®. Make sure to whitelist only those two networks.

To use the ZEN gateway you need to use the following data:

Please contact us for ZEN Shop UUID. Please make sure to provide the email address of your ZEN business account and your ZEN Shop ID in the message.

IMPORTANT: To use ZEN gateway, you need to define the supported card networks:

IMPORTANT: To use ZEN gateway, you need to define the supported method to Cryptogram_3DS:

Offering Google Pay in your Android app

To learn how to offer Google Pay in your store, please see the below steps with linked Google knowledge sources.

1. Follow Google’s Overview of Google Pay.
2. Set up your app and Google Account for Google Pay 
3. Review your integration and fill Google Pay integration checklist
4. Request production access.
5. Ensure that your Android device has Google Play services version 18.0.0 or higher.
6. Test Google Pay with ZEN in your app.

IMPORTANT

ZEN only accepts Visa and Mastercard®. Make sure to whitelist only those two networks.

To use the ZEN gateway you need to use the following data:

Please contact us for ZEN Shop UUID. Please make sure to provide the email address of your ZEN business account and your ZEN Shop ID in the message.

IMPORTANT: To use ZEN gateway you need to define the supported card networks:

IMPORTANT: To use ZEN gateway, you need to define an allowed authentication method:

Instant Payment Notifications

Instant Payment Notifications (IPN) inform you about transaction status updates, e.g., about changing the status from pending to rejected.

ZEN sends you an Instant Payment Notification (IPN) after each transaction.

IPN with status "ACCEPTED" is confirmation of successful transaction. Once you receive IPN with status "ACCEPTED" you can finalize the order.

There are two ways to provide the IPN URL address to ZEN:

• In the Credentials tab in the ZEN panel, you can provide the IPN URL address.
• If you are using the API integration or the Checkout Integration with each request, you can provide customIpnUrl for this request as an optional field. If you leave the field blank, the IPN URL address from pt. 1 will be used.

To verify whether the IPN is sent by ZEN, you should use the IPN API Secret. See where to find your credentials.

You should hash particular values using sha256 and compare results with the hashed values from the received IPN.

Hash is calculated as follows:

Merchant Secret used for this example

with

We get

which gives 

Received hash is equal to 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:

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

Rejection codes

This feature is only supported only in API Integration.

In the below table, you'll find an explanation of all the rejection codes available in the system.