API integration

 Before you begin

• First, prepare all the credentials for this integration. See how to get the credentials.
• Next, get a list of all available payment methods. See the list of payment methods.
• Keep in mind that each purchase and refund are followed by an IPN. Learn more about IPN.
• 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.

Name	chanel code	supported currencies	transaction amountmin	transaction amountmax	API Integration payment type(POST /transactions; paymentSpecificData.type)
ApplePay	PCL_APPLEPAY	AED, AUD, BGN, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, KES, MXN, NOK, NZD, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, UGX, USD, ZAR	0.01 EUR	10,000 EUR	external_payment_token
Bancontact	PCL_BANCONTACT	EUR	0.01 EUR	10,000 EUR	general
BLIK	PCl_BLIK_REDIRECT	PLN	0.01 PLN	100,000 PLN	general
	PCL_BLIK	PLN	0.01 PLN	9,999.99 PLN	blik
GooglePay	PCL_GOOGLEPAY	AED, AUD, BGN, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, KES, MXN, NOK, NZD, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, UGX, USD, ZAR	0.01 EUR	100,000 EUR	external_payment_token
Ideal	PCL_IDEAL	EUR	0.01 EUR	10,000 EUR	general
Mastercard	PCL_CARD	AED, AUD, BGN, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, KES, MXN, NOK, NZD, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, UGX, USD, ZAR	0.01 EUR	100,000 EUR	onetime, oneclick, auth_check, recurring_fulldata, recurring_token, unscheduled
Neosurf	PCL_NEOSURF	AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, XOF, ZAR	1 EUR	10,000 EUR	general
Neteller	PCL_NETELLER_WALLET	EUR	0.01 EUR	100,000 EUR	general
Pay By Link	PCL_PBL_ALIOR PCL_PBL_BNPPARIBAS PCL_PBL_BOS PCL_PBL_BZWBK PCL_PBL_CITI PCL_PBL_CREDITAGRICOLE PCL_PBL_MILLENNIUM PCL_PBL_NOBLE PCL_PBL_PEKAO24 PCL_PBL_IPKO PCL_PBL_GETIN PCL_PBL_INTELIGO PCL_PBL_IDEABANK PCL_PBL_ING PCL_PBL_MTRANSFER PCL_PBL_PBS PCL_PBL_NEST PCL_PBL_PLUS PCL_PBL_BS	PLN	1 PLN	100,000 PLN	general
PayByZen	PCL_PBZ	EUR,GBP,PLN,USD	0.01 EUR	1,000,000 EUR	general
PayPal	PCL_PAYPAL	AUD, BRL, CAD, CZK, DKK, EUR, HUF, HKD, ILS, JPY, MYR, MXN, NOK, NZD, PHP, PLN, GBP, RUB, SGD, SEK, CHF, TWD, TRY, THB, USD	0.01 EUR	100,000 EUR	general
Paysafecard	PCL_PAYSAFECARD_WALLET PCL_PAYSAFECARD_PINCODE	AUD, CAD, CZK, DKK, EUR, GBP, HUF, NOK, PLN, RON, SEK, USD	0.01 EUR	Tabela	general
Paysafecash	PCL_PAYSAFECASH	EUR, CAD, BGN, CZK, HUF, GBP, USD, PLN, MXN, RON, SEK, CHF	0.01 EUR	1000 EUR	general
Skrill	PCL_SKRILL_WALLET	EUR	0.01 EUR	100,000 EUR	general
Dragon	PCL_DRAGON	EUR	15 EUR	100,000 EUR	dragon
Trustly	PCL_TRUSTLY	EUR, PLN, DKK, SEK, NOK, CZK	0.01 EUR	100,000 EUR	trustly
Union Pay	PCL_UPI	EUR, BGN, HRK, CZK, HUF, DKK, ISK, CHF, NOK, PLN, RON, SEK, GBP	0.01 MYR/CNY/EUR	Single Transaction Limit USD – $300.000 Single Card Limit Per Day USD  – $500.000 100,000 MYR/CNY/EUR	general
Visa	PCL_CARD	USD, AUD, GBP, BGN, CAD, CZK, DKK, EUR, HKD, HUF, ILS, JPY, KES, MXN, NZD, NOK, PLN, QAR, CNY, RON, SAR, SGD, ZAR, SEK, CHF, THB, TRY, UGX, AED	0.01 EUR	100,000 EUR	onetime, oneclick, auth_check, recurring_fulldata, recurring_token, unscheduled
Webmoney	PCL_WEBMONEY	EUR, USD	0.01 EUR	100,000 USD; 10,000 EUR	general
WeChat	PCL_WECHAT	CNY	0.01 CNY	50,000 CNY	general

Payment Link

Payment links are URL addresses that directly redirect users to the payment page. They can be configured for any selected amount, not necessarily for a specific product or group of products. When a user selects such a link, they are immediately redirected to the payment page, where all the selected products are already added to the cart. All they have to do is make the payment and place the order. This is why payment links are a convenient tool, allowing users to have direct access to the payment process from any page where such a link appears, whether it’s on a store page, blog, or social media.

The key features and benefits of payment links include:

• Variety of Payment Methods: Payment links offer users the option to use all available payment methods that have been configured in the store.
• Currency Specification: You can specify the currencies in which users can make payments for each payment link, increasing adaptability to different customers.
• Validity Period: Each payment link can have a specified validity period, giving you control over when it becomes inactive.
• Flexibility: Users can open a payment link multiple times and on various devices until they complete the payment. This means they have more time to make their decision.

Creating a payment link is possible through the API interface. However, it’s important to note that these links initiate the payment process, which is handled by ZEN. API integration introduces new endpoints, such as /payment-links POST and GET, as well as /payment-links/{id} PATCH and GET. The authorization process remains unchanged, with only the content of the request needing adjustment to accommodate new queries. More information on this can be found in the API documentation.

 

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.

• Enable saving and tokenizing cards
• Initialize payments with a saved tokenized card:
  • First, 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. 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:

• Follow the tutorial described in Google Pay documentation.
• Review your integration and fill Google Pay integration checklist.
• Request production access.
• Setup your website and launch your integration.
• 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.

• Follow Google’s Overview of Google Pay.
• Set up your app and Google Account for Google Pay 
• Review your integration and fill Google Pay integration checklist
• Request production access.
• Ensure that your Android device has Google Play services version 18.0.0 or higher.
• 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:

 

Transfer to card 

Transfer to Card transaction is a service that involves transferring funds from the Merchant’s account to the card account of the Recipient. This is a one-way operation that allows the transfer of funds from one account to another to fund the card of the owner.

Advantages of Transfer to Card:

• Speed and Convenience: Transfer to Card enables quick and convenient transfer of funds to payment cards, which is particularly useful for urgent payments such as salaries or insurance claims.
• Payment Distribution: This service can be used for the distribution of various types of payments, including salaries, investment dividends, merchant rebates, and more.
• Automation: Processing transactions using an API allows for process automation, which can expedite fund transfers and reduce the risk of human errors.

Description of the Transfer to Card Process is available in the API documentation.

 

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.