See the complete API documentation.
In the API integration, you can process two types of transactions:
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.
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
In the below table, you can find all payment methods available for configuration through API.
Name | chanel code | supported currencies |
transaction amount min |
transaction amount max |
API Integration payment type (POST /transactions; paymentSpecificData.type) |
ApplePay | PCL_APPLEPAY | EUR | 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 | EUR | 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, HRK, 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, HRK, 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, HRK, 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, HRK, 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 |
PCL_WECHAT | CNY | 0.01 CNY | 50,000 CNY | general |
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.
To create fingerPrintId, you should implement following code into your website or app.
Code:
<html>
<head>
<script src="https://cdn.deviceinf.com/js/v4/agent.js"></script>
</head>
<body>
<script>
seon.config({
host: "deviceinf.com",
session_id: "UNIQUE SESSION ID",
audio_fingerprint: true,
canvas_fingerprint: true,
webgl_fingerprint: true,
onSuccess: function(message) {
},
onError: function(message) {
}
});
seon.getBase64Session(function(data) {
if (data) {
console.log("Returned Data use for fingerprint in api", data);
} else {
}
});
</script>
</body>
</html>
Then, send the retrieved fingerprint (“data” from console.log within seon.getBase64Session function) value to ZEN.
POST /transactions in fraudFields.fingerPrintId
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
type - onetime
saveCard - true
authorization (once payment is authorized, ZEN will instantly cancel it and provide money back to the payer)
type - auth_check
saveCard - true
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:
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.
cardToken - contains the token data you've received in Step 1
type - is set to one click
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 start the integration process, you must first go through the registration process. For more information, see the following links:
To create a Payment Processing Certificate, please contact us for the Certificate Signing Request with the following information:
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
To integrate your e-store or iOs app with Apple Pay, please check the below knowledge sources:
IMPORTANT
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:
/createNewTransaction PaymentSpecificData Type:external_payment_token
This technical guide describes how to connect Google PAYwith your ZEN API .
For more information, please check the Google Pay™ documentation.
Before you start the integration process, please see the below knowledge sources:
https://developers.google.com/pay/api/web/overview?hl=en&authuser=2
https://developers.google.com/pay/api/android/overview?authuser=2
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.
To integrate your website with Google Pay:
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:
‘gateway’: ‘zen’
‘gatewayMerchantId’ : ‘your_ZEN_Shop_UUID’
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:
const allowedCardNetworks = [""MASTERCARD"", ""VISA""];
IMPORTANT: To use ZEN gateway, you need to define the supported method to Cryptogram_3DS:
const allowedCardAuthMethods = [""CRYPTOGRAM_3DS""];
To learn how to offer Google Pay in your store, please see the below steps with linked Google knowledge sources.
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:
private static JSONObject getGatewayTokenizationSpecification() throws JSONException {
return new JSONObject() );
}};
}
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:
private static JSONArray getAllowedCardNetworks() {
return new JSONArray()
.put(""MASTERCARD"")
.put(""VISA"");
}
IMPORTANT: To use ZEN gateway, you need to define an allowed authentication method:
private static JSONArray getAllowedCardAuthMethods() {
return new JSONArray()
.put(""CRYPTOGRAM_3DS"");
}
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. There are two ways to provide the IPN URL address to ZEN:
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:
sha256({transaction.merchantTransactionId}{transaction.currency}{transaction.amount}{transactionStatus}{merchantIpnSecret})
""type"":""TRT_PURCHASE"",
""transactionId"":"" 2d36ff20-017d-4c63-b626-407edb369cc2"",
""merchantTransactionId"":"" feb78e88-47bc-428a-8ea4-806535aaf2de"",
""amount"":""100"",
""currency"":""PLN"",
""status"":""PENDING"",
""hash"":""28EE6604A8A40ACC8B8CE0B8DE9AAC87A4E24BBF0388A48ED164E512C8073C7E"",
""signature"":""D3739E5ADCC20E436DEE8F386C81B1C3ACCCE0558FAB65EC924564F998F983EE"",
""paymentMethod"":{
""name"":""PME_PBZ"",
""channel"":""PCL_PBZ"",
""parameters"":{
}
},
""customer"":{
""firstName"":""John"",
""lastName"":""Doe"",
""email"":""john@doe.pl"",
""ip"":""172.89.0.1"",
""country"":""US""
},
""securityStatus"":""pending"",
""riskData"":{
},
""email"":""john@doe.pl""
}
Merchant Secret used for this example
aeb8e7bf-0009-4f30-b521-1136fd336ae6
with
merchantTransactionID = feb78e88-47bc-428a-8ea4-806535aaf2de
currency = PLN
amount = 100
transactionStatus = PENDING
merchantIpnSecret = aeb8e7bf-0009-4f30-b521-1136fd336ae6
We get
sha256(feb78e88-47bc-428a-8ea4-806535aaf2dePLN100PENDINGaeb8e7bf-0009-4f30-b521-1136fd336ae6)
which gives
hash = 28EE6604A8A40ACC8B8CE0B8DE9AAC87A4E24BBF0388A48ED164E512C8073C7E
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:
E00001
Creating new transaction in payment service provider failed.
E00002
Transaction was expired on the payment service provider side.
E00003
Creating refund transaction in payment service provider failed.
E00004
Transaction was rejected by payment service provider.
E00005
Checking status of transaction limit was exceeded.
E00006
Refund attempts limit was exceeded.
E00007
Capturing transaction in payment service provider failed.
S00001
Technical error
S00002
Technical error
E40001
Transaction already exists
E40002
Reporting criteria unavailable
E40003
Reporting criteria is inactive
E40004
MID is inactive
E40005
Amount must be greater than 0
E40006
The amount exceeds the maximum permitted amount
E40007
E40008
E40009
E40010
E40011
E40012
E40013
E40014
E40015
E40016
E40017
E40018
E40019
E40020
E40021
E40022
E40023
E40024
E40025
E40026
E40027
E40028
E40029
E40030
E40031
E40032
E40033
E40034
E40035
E40036
E40037
E40038
E40039
E40040
E40041
E40042
E40043
E40044
E40045
E40046
E40047
E40049
E40050
E40051
E40052
E40053
E40054
E40055
E40056
E40057
E40058
E40059
E40060
E40061
E40062
E40063
E40064
E40065
E40066
E40067
E40068
E40069
E40070
E40071
E40072
E40073
E40074
E40075
E40076
E40077
E40078
E40079
E40080
E40081
E40082
E40083
E40084
E40085
E40086
E40087
E40088
E40089
E40090
E40091
E40092
E40093
E40094
E40095
E40096
E40097
E40098
E40099
E40100
E40101
E40102
E40103
E40104
E40105
E40106
E40107
E40108
E40109
E40110
E40111
E40112
E40113
E40114
E40115
E40116
E40117
E40118
E40119
E40120
E40121
E40122
E40123
E40124
E40125
E40126
E40127
E40128
C00022
C00023
C40087
C20087
C10007
C40088
Daily Usage Limit Reached - Try again later
C20082
Challenge Mandate requested but could not be performed
C20087
Card type not supported in 3DS
E40330
Transaction failed, please refer to issuer
E40331
Message format error
E40333
Transaction does not exist / Abandoned transaction
E40334
Original transaction does not exist or state is incorrect
E40337
Invalid card number
E40339
Wrong PIN, expiry date or CVN2
E40340
Wrong cardholder ID information, mobile phone number or CVN2
E40341
You have entered your PIN too many times
E40342
Your card does not support this service