ZEN eCommerce Public API (0.0.1 Alpha)

Download OpenAPI specification:Download

ZEN allows you to start accepting more than 150 global and local payment options (including credit cards, instant bank transfers, and many more). The following document will guide you through integration process and introduce to main features of the Public API.

1. Allowed HTTPs requests: 

  • PUT: To create resource  
  • POST: Update resource 
  • GET: Get a resource or list of resources 
  • DELETE: To delete resource 

 2. Description ousual server responses: 

  • 200 --OK - the request was successful (some API calls may return 201 instead). 
  • 201 --> Created - the request was successful and a resource was created. 
  • 204 --> No Content - the request was successful but there is no representation to return (i.e. the response is empty). 
  • 400 --> Bad Request - the request could not be understood or was missing required parameters. 
  • 401 --> Unauthorized - authentication failed or user doesn't have permissions for requested operation. 
  • 403 --> Forbidden - access denied 
  • 404 -->Not Found - resource was not found. 
  • 405 --> Method Not Allowed - requested method is not supported for resource. 

3. API Keys 

To start using ZEN eCommerce Public API user must be able to authorize his requests. It is done by adding API key to the request header. In order to retrieve (or re-generate) your API key please: 

  1. Log in to ZEN
  2. Go to Online Payments section and select Store Settings
  3. Go to API & Documentation page
  4. Copy Terminal API key 

4. IPN API Secrets 

In order to verify whether IPN (instant payment notification) is sent by ZEN you should use the IPN API Secret. The below values are hashed using sha256 algorithm to create “signature”:

signature = sha256(${transaction.merchantTransactionId}${transaction.currency}${transaction.amount}${merchantIpnSecret})

 In order to retrieve (or re-generate) your IPN API secret please: 

  1. Log in to ZEN
  2. Go to eCommerce section and select your store
  3. Go to Integration section
  4. Copy IPN API secret from the Terminal API credentials section 

 

Example of an IPN: 

{"type":"TRT_PURCHASE","transactionId":"dec7ec81-2a1a-4304-8ded-1e2e7cd4be7c","merchantTransactionId":"7e21be42-5768-4ce3-b43d-66e43c7e52c5","amount":"6.99","currency":"RON","status":"PENDING","signature":"14A7D8636A60C73BF4D093F5B334A1B31850F7CE7758EAB537B1A2F8CEEF6E2B","paymentMethod":{"pspId":"PSP_PAYSAFECARD","name":"PME_PAYSAFECARD","channel":"PCL_PAYSAFECARD_WALLET","parameters":{}},"customer":{"id":"1213722e-5cff-48ff-bcea-6d3714a902a8","email":"john.doe@yahoo.com","ip":"91.124.32.78","country":"PL"},"securityStatus":"pending","riskData":{},"email":"john.doe@yahoo.com"} 

 

Authentication

ApiKey

Security Scheme Type API Key
Header parameter name: Authorization

Terminals

How to check which payment methods are turned on a given Terminal

Returns information about payment methods on a Terminal

ZEN uses virtual Terminals to manage payment methods used by merchants. By adding currency parameter to the request you will be returned with all payment methods which are turned on the terminal and support payments in this currency. Each store you will open uses separate terminal. It allows you not only to have separate Terminal settings per each store, but also helps to verify which transactions come from which store.

Authorizations:
query Parameters
currency
string 3 characters ^[A-Z]+$
Example: currency=PLN

Currency

header Parameters
request-id
required
string [ 38 .. 1024 ] characters ^[a-zA-Z0-9?&:\_\|\-\/=.,#\s]+$
Example: |us04oqdnzFQVr0rITD9/c9OvDRE2sXVfwerv.

A unique identifier generated by requesting client

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transactions

How to create, refund, cancel, capture and view details of your transactions

Create transaction

Allows you to create a transaction (by sending transaction parameteres to ZEN). Important! For some payment methods returnUrl will be returned to you. In order to proceed with the transaction customer needs to be redirected to that URL.

Authorizations:
header Parameters
request-id
required
string [ 38 .. 1024 ] characters ^[a-zA-Z0-9?&:\_\|\-\/=.,#\s]+$
Example: |us04oqdnzFQVr0rITD9/c9OvDRE2sXVfwerv.

A unique identifier generated by requesting client

Request Body schema: application/json
merchantTransactionId
required
string [ 1 .. 128 ] characters ^[a-zA-Z0-9?&:\-\/=.,#]+$

Id of the transaction provided by merchant.

paymentChannel
required
string^([a-z](-?[a-z0-9])*|[A-Z](_?[A-Z0-9])*)$

Id of the payment channel for selected payment method.

amount
required
string^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$

Amount of the transaction.

currency
required
string 3 characters ^[A-Z]+$

Currency code in ISO 4217 alphabetic code

customIpnUrl
string <uri> <= 256 characters

URL address used by ZEN to send IPN to

object or object
required
Array of objects

Sum of items' amount should be equal to transaction amount

required
object
object
object
object

Responses

Request samples

Content type
application/json
{
  • "merchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
  • "paymentChannel": "PCL_CARD",
  • "amount": "123.04",
  • "currency": "PLN",
  • "customIpnUrl": "https://ipn-pay.g2a.com/ipn",
  • "fraudFields": {
    },
  • "items": [
    ],
  • "customer": {
    },
  • "paymentSpecificData": {
    },
  • "billingAddress": {
    },
  • "shippingAddress": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchantAction": {},
  • "merchantTransactionId": "string",
  • "amount": "123.04",
  • "currency": "PLN",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "type": "TRT_REFUND",
  • "status": "CANCELED",
  • "paymentChannel": "PCL_CARD",
  • "actions": {
    },
  • "fraudFields": {
    },
  • "rejectCode": "E40199",
  • "refunds": [
    ],
  • "meta": {
    },
  • "customer": {
    },
  • "cardInfo": {