API docs by Redocly

ZEN eCommerce Public API (1.0.2)

Download OpenAPI specification:Download

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

1. Allowed HTTPs requests: 

  • POST: To create a resource  
  • PUT: To update a resource 
  • GET: To get a resource or a list of resources 
  • DELETE: To delete a resource 

 2. Description of usual 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 does not have permissions for requested operation 
  • 403 --> Forbidden  - access denied 
  • 404 --> Not Found - the resource was not found 
  • 405  --> Method Not Allowed - requested method is not supported for the resource 

3. API Integration Guidelines 

To start using ZEN eCommerce Public API please follow these instructions:  
https://www.zen.com/developer/api-integration#before-you-begin  

4. IPN API Secrets 

Instant Payment Notification (IPN) informs you about transaction status updates, e.g., about changing the status from pending to rejected.
Information abut IPN is available in the following link: 
https://www.zen.com/developer/api-integration#ipn

4. Error codes

The full list of error codes can be found here: 
https://www.zen.com/developer/api-integration#rejection-codes

Authentication

ApiKey

Security Scheme Type: API Key
Header parameter name: Authorization

Terminals

Check which payment methods are enabled on a given Terminal

Return information about payment methods on a Terminal

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

Authorizations:
ApiKey
query Parameters
customer-id
required
string <uuid>

A customer identifier

transactionType
required
string^TRT(_[A-Z0-9]+)+$
Example: transactionType=TRT_PURCHASE

Type of the transaction. For regular transactions TRT_PURCHASE and TRT_REFUND should be used.

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

amount

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

Currency

itemsPerPage
string^[1-9][0-9]*$
Default: "10"

Limit of results

page
string^[1-9][0-9]*$
Default: "1"

Page of results

direction
string
Default: "asc"
Enum: "asc" "desc"

Direction of order

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

A unique identifier generated by the requesting client

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

An unique Terminal ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transactions

Create, refund 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:
ApiKey
header Parameters
request-id
required
string [ 38 .. 1024 ] characters ^[a-zA-Z0-9?&:_|\-\/=+.,#\s]+$
Example: |us04oqdnzFQVr0rITD9/c9OvDRE2sXVfwerv.

A unique identifier generated by requesting client

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

An unique Terminal ID

Request Body schema: application/json
object

Can only be used after using POST Calculate authorization amount.

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

comment
string or null <= 512 characters
required
object
required
Array of objects

Sum of items amount should be equal to transaction amount

required
object
required
object
object
object
object

Information about transaction cashback.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "redirectUrl": "https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=",
  • "imageUrl": "https://notifications.zen-test.com/eps/image/567afec2-6189-4731-9cb3-c6d4bb4fd345/1579592876",
  • "merchantAction": {},
  • "merchantTransactionId": "string",
  • "originMerchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
  • "amount": "123.04",
  • "currency": "PLN",
  • "fee": {
    },
  • "subsidiaryData": {
    },
  • "authorization": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "type": "TRT_REFUND",
  • "status": "AUTHORIZED",
  • "topupTransferStatus": "PENDING",
  • "paymentChannel": "PCL_CARD",
  • "actions": {
    },
  • "fraudFields": {
    },
  • "rejectCode": "E40199",
  • "rejectReason": "Client doesn't have enough money.",
  • "refunds": [
    ],
  • "meta": {
    },
  • "customer": {
    },
  • "cardInfo": {
    },
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "items": [
    ],
  • "verifyReturnmac": "7e92079c-79e1-47bd-af9d-80c2f7783037",
  • "cashback": {
    },
  • "source": {
    }
}

Get transaction details using ZEN ID

Returns transaction details using ZEN ID. It's Payment ID from my.zen.com platform

Authorizations:
ApiKey
path Parameters
id
required
string <uuid>
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Unique identifier

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

Unique identifier generated by requesting client

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

An unique Terminal ID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "redirectUrl": "https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=",
  • "imageUrl": "https://notifications.zen.com/eps/image/567afec2-6189-4731-9cb3-c6d4bb4fd345/1579592876",
  • "merchantAction": {},
  • "merchantTransactionId": "string",
  • "amount": "123.04",
  • "currency": "PLN",
  • "fee": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "type": "TRT_REFUND",
  • "status": "AUTHORIZED",
  • "paymentChannel": "PCL_CARD",
  • "actions": {
    },
  • "fraudFields": {},
  • "rejectCode": "E40199",
  • "rejectReason": "Client doesn't have enough money.",
  • "refunds": [
    ],
  • "meta": {
    },
  • "customer": {
    },
  • "cardInfo": {
    },
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "items": [
    ],
  • "verifyReturnmac": "7e92079c-79e1-47bd-af9d-80c2f7783037",
  • "cashback": {
    }
}

Get transaction details using merchant transaction ID

Returns transaction details using Merchant transaction ID

Authorizations:
ApiKey
path Parameters
merchantTransactionId
required
string [ 1 .. 128 ] characters ^[a-zA-Z0-9?&:\-\/=.,#]+$
Example: 23beb187-f8a3-44b8-9ef8-b31180358dd3

Unique merchant transaction identifier

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

Unique identifier generated by requesting client

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

An unique Terminal ID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "redirectUrl": "https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=",
  • "imageUrl": "https://notifications.zen.com/eps/image/567afec2-6189-4731-9cb3-c6d4bb4fd345/1579592876",
  • "merchantAction": {},
  • "merchantTransactionId": "string",
  • "amount": "123.04",
  • "currency": "PLN",
  • "fee": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "type": "TRT_REFUND",
  • "status": "AUTHORIZED",
  • "paymentChannel": "PCL_CARD",
  • "actions": {
    },
  • "fraudFields": {},
  • "rejectCode": "E40199",
  • "rejectReason": "Client doesn't have enough money.",
  • "refunds": [
    ],
  • "meta": {
    },
  • "customer": {
    },
  • "cardInfo": {
    },
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "items": [
    ],
  • "verifyReturnmac": "7e92079c-79e1-47bd-af9d-80c2f7783037",
  • "cashback": {
    }
}

Process transaction refunds using initial transaction's ID, received in POST /transaction

Processes transaction refunds using initial transaction's ID, received in POST /transaction

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

Unique identifier generated by requesting client

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

An unique Terminal ID

Request Body schema: application/json
comment
string or null <= 512 characters
amount
required
string^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$

Transaction amount

transactionId
required
string <uuid>

Transaction ID generated during create transaction process

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

Currency code in ISO 4217 alphabetic code

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

Id of the refund provided by merchant.

originMerchantTransactionId
string [ 1 .. 128 ] characters

Origin Id of the transaction provided by merchant.

object

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "amount": "123.04",
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
  • "currency": "PLN",
  • "merchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
  • "originMerchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "parentTransactionId": "f8033cf6-befa-47f4-a48a-b915b8c72a71",
  • "redirectUrl": "https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=",
  • "imageUrl": "https://notifications.zen.com/eps/image/567afec2-6189-4731-9cb3-c6d4bb4fd345/1579592876",
  • "merchantAction": {},
  • "merchantTransactionId": "string",
  • "amount": "123.04",
  • "currency": "PLN",
  • "fee": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "type": "TRT_REFUND",
  • "status": "AUTHORIZED",
  • "paymentChannel": "PCL_CARD",
  • "actions": {
    },
  • "fraudFields": {},
  • "rejectCode": "E40199",
  • "rejectReason": "Client doesn't have enough money.",
  • "refunds": [
    ],
  • "meta": {
    },
  • "customer": {
    },
  • "cardInfo": {
    },
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "items": [
    ],
  • "verifyReturnmac": "7e92079c-79e1-47bd-af9d-80c2f7783037",
  • "cashback": {
    }
}

Create new authorization attempt on the same TRX transaction in case of expired or rejected previous authorization

Creates new authorization attempt on the same TRX transaction in case of expired or rejected previous authorization

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

Unique identifier generated by requesting client

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

An unique Terminal ID

Request Body schema: application/json
comment
string or null <= 512 characters
transactionId
required
string <uuid>

Transaction ID generated during create transaction process

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

ID of transaction provided by merchant

required
object

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
  • "merchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
  • "paymentSpecificData": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "redirectUrl": "https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=",
  • "imageUrl": "https://notifications.zen.com/eps/image/567afec2-6189-4731-9cb3-c6d4bb4fd345/1579592876",
  • "merchantAction": {},
  • "merchantTransactionId": "string",
  • "amount": "123.04",
  • "currency": "PLN",
  • "fee": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "type": "TRT_REFUND",
  • "status": "AUTHORIZED",
  • "paymentChannel": "PCL_CARD",
  • "actions": {
    },
  • "fraudFields": {},
  • "rejectCode": "E40199",
  • "rejectReason": "Client doesn't have enough money.",
  • "refunds": [
    ],
  • "meta": {
    },
  • "customer": {
    },
  • "cardInfo": {
    },
  • "billingAddress": {
    },
  • "shippingAddress": {
    },
  • "items": [
    ],
  • "verifyReturnmac": "7e92079c-79e1-47bd-af9d-80c2f7783037",
  • "cashback": {
    }
}

payment-profiles

Save and fetch credit card details (for one-click payments)

Fetch saved card list

Removes saved card

Authorizations:
ApiKey
query Parameters
itemsPerPage
string^[1-9][0-9]*$
Default: "10"

Limit of results

page
string^[1-9][0-9]*$
Default: "1"

Page of results

direction
string
Default: "asc"
Enum: "asc" "desc"

Direction of order

sortBy
string
Default: "createdAt"
Value: "createdAt"

column sorting

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

A unique identifier generated by requesting client

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

An unique Terminal ID

extended
string = 1 characters

Return data with Meta

external-customer-id
string

A customer identifier from merchant system

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "meta": {
    }
}

Removes saved card

Removes saved card

Authorizations:
ApiKey
path Parameters
id
required
string <uuid>
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

An unique identifier

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

A unique identifier generated by requesting client

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

An unique Terminal ID

external-customer-id
string

A customer identifier from merchant system

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Fetch saved card

Fetch saved card

Authorizations:
ApiKey
path Parameters
id
required
string <uuid>
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

An unique identifier

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

external-customer-id
string

A customer identifier from merchant system

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchantId": "string",
  • "shopId": "string",
  • "terminalId": "string",
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "firstTransactionId": "03056aca-c5f2-4f6b-a174-27e4af663155",
  • "cpsCardId": "string",
  • "cardName": "string",
  • "cardHolderName": "string",
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "addressCity": "string",
  • "addressCountry": "string",
  • "addressState": "string",
  • "addressZip": "string",
  • "organization": "string",
  • "brand": "string",
  • "bank": "string",
  • "country": "str",
  • "tokenizationMethod": "apple_pay",
  • "last4": "stri",
  • "expMonth": "st",
  • "expYear": "stri",
  • "verificationStatus": "st",
  • "verificationDate": "st",
  • "status": "verified",
  • "isDefault": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "string"
}

Update details for credit card

Update details for credit card

Authorizations:
ApiKey
path Parameters
id
required
string <uuid>
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

An unique identifier

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

external-customer-id
string

A customer identifier from merchant system

Request Body schema: application/json

Card object that needs to be added to the database

cardName
string or null <= 128 characters
cardHolderName
string or null <= 128 characters
addressLine1
string or null <= 128 characters
addressLine2
string or null <= 128 characters
addressCity
string or null <= 128 characters
addressCountry
string or null <= 32 characters
addressState
string or null <= 32 characters
addressZip
string or null <= 16 characters
expMonth
string [ 1 .. 2 ] characters
expYear
string [ 1 .. 4 ] characters
isDefault
boolean

Responses

Request samples

Content type
application/json
{
  • "cardName": "string",
  • "cardHolderName": "string",
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "addressCity": "string",
  • "addressCountry": "string",
  • "addressState": "string",
  • "addressZip": "string",
  • "expMonth": "st",
  • "expYear": "stri",
  • "isDefault": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchantTransactionId": "string",
  • "shopId": "string",
  • "terminalId": "string",
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "firstTransactionId": "03056aca-c5f2-4f6b-a174-27e4af663155",
  • "cpsCardId": "string",
  • "cardName": "string",
  • "cardHolderName": "string",
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "addressCity": "string",
  • "addressCountry": "string",
  • "addressState": "string",
  • "addressZip": "string",
  • "organization": "string",
  • "brand": "string",
  • "bank": "string",
  • "country": "str",
  • "tokenizationMethod": "apple_pay",
  • "last4": "stri",
  • "expMonth": "st",
  • "expYear": "stri",
  • "verificationStatus": "st",
  • "verificationDate": "st",
  • "status": "verified",
  • "isDefault": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "string"
}

authorization

Calculate authorization values for fee and currency convertion

Calculate authorization amount

Calculate authorization amount

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

A unique identifier generated by requesting client

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

An unique Terminal ID

Request Body schema: application/json
merchantTransactionId
required
string
amount
required
string
currency
required
string
authorizationCurrency
required
string
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "merchantTransactionId": "string",
  • "amount": "string",
  • "currency": "string",
  • "authorizationCurrency": "string",
  • "data": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

transfer to card

Processing Transfer to card transactions using ZEN eCommerce Public API.

Create customer

Create customer

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

A unique identifier generated by requesting client

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

An unique Terminal ID

Request Body schema: application/json
merchantCustomerId
required
string [ 1 .. 128 ] characters
id
string [ 1 .. 128 ] characters
firstName
string or null <= 128 characters
lastName
string or null <= 128 characters
userName
string or null <= 128 characters
description
string or null <= 256 characters
email
string or null <email>

Responses

Request samples

Content type
application/json
{
  • "merchantCustomerId": "string",
  • "id": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "userName": "string",
  • "description": "string",
  • "email": "[email protected]"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchantId": "string",
  • "status": "new",
  • "firstName": "string",
  • "lastName": "string",
  • "userName": "string",
  • "description": "string",
  • "email": "[email protected]",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Fetch saved subscription customer list

Fetch saved subscription customer list

query Parameters
itemsPerPage
string^[1-9][0-9]*$
Default: "10"

Limit of results

page
string^[1-9][0-9]*$
Default: "1"

Page of results

direction
string
Default: "asc"
Enum: "asc" "desc"

Direction of order

sortBy
string
Default: "createdAt"
Value: "createdAt"

column sorting

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Fetch saved subscription customer by customer external id

Fetch saved subscription customer by customer external id

path Parameters
merchantCustomerId
required
string <uuid>
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

An unique customer external identifier

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchantId": "string",
  • "status": "new",
  • "firstName": "string",
  • "lastName": "string",
  • "userName": "string",
  • "description": "string",
  • "email": null,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Update saved subscription customer

Update saved subscription customer

path Parameters
merchantCustomerId
required
string <uuid>
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

An unique customer external identifier

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

Request Body schema: application/json

Customer object that needs to be added to the database

id
string <uuid>
merchantId
string [ 1 .. 32 ] characters
status
string
Enum: "new" "confirmed"
firstName
string or null <= 128 characters
lastName
string or null <= 128 characters
userName
string or null <= 128 characters
description
string or null <= 256 characters
email
string or null <email>

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchantId": "string",
  • "status": "new",
  • "firstName": "string",
  • "lastName": "string",
  • "userName": "string",
  • "description": "string",
  • "email": "[email protected]"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "new",
  • "firstName": "string",
  • "lastName": "string",
  • "userName": "string",
  • "description": "string",
  • "email": "[email protected]",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Removes saved subscription customer

Removes saved subscription customer

path Parameters
merchantCustomerId
required
string <uuid>
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

An unique customer external identifier

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

Responses

Response samples

Content type
application/json
{
  • "success": true
}

To get a list of saved card/s for specific Customer

Return saved payout card list V2

query Parameters
itemsPerPage
string^[1-9][0-9]*$
Default: "10"

Limit of results

page
string^[1-9][0-9]*$
Default: "1"

Page of results

direction
string
Default: "asc"
Enum: "asc" "desc"

Direction of order

sortBy
string
Default: "createdAt"
Value: "createdAt"

column sorting

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

customer-id
string <uuid>

A customer identifier

external-customer-id
string

A customer identifier from merchant system

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Once Customer/Recipient was saved it is possible to save his cards

Add payout card V2

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

customer-id
string <uuid>

A customer identifier

external-customer-id
string

A customer identifier from merchant system

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "card": {
    }
}

Response samples

Content type
application/json
{
  • "organization": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "cardName": "string",
  • "recipientFirstName": "string",
  • "recipientLastName": "string",
  • "last4": "stri",
  • "fundsAvailability": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Removes saved payout card V2

Removes saved payout card V2

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

customer-id
string <uuid>

A customer identifier

external-customer-id
string

A customer identifier from merchant system

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Create payout

Create Payout, as result of this we will receive basic informations. Transfer to card transaction is one way transaction.

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

A unique identifier generated by requesting client

terminal-id
required
string [ 3 .. 128 ] characters ^[a-zA-Z0-9\-]+$
Example: ABC1234

ID of the ZEN terminal

Request Body schema: application/json
comment
string or null <= 512 characters
merchantTransactionId
required
string [ 1 .. 128 ] characters ^[a-zA-Z0-9?&:\-\/=.,#|+_$\[\]€ ]+$

Id of the transaction provided by merchant.

originMerchantTransactionId
string [ 1 .. 128 ] characters

Origin 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. Use: PCL_CARD

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 example: https://ipn-pay.zen.com/ipn

required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "merchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
  • "originMerchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
  • "paymentChannel": "PCL_CARD",
  • "amount": "123.04",
  • "currency": "PLN",
  • "customIpnUrl": "https://ipn-pay.zen.com/ipn",
  • "customer": {
    },
  • "paymentSpecificData": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "parentTransactionId": "f8033cf6-befa-47f4-a48a-b915b8c72a71",
  • "merchantTransactionId": "string",
  • "originMerchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
  • "amount": "123.04",
  • "currency": "PLN",
  • "fee": {
    },
  • "authorization": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "type": "TRT_REFUND",
  • "status": "ACCEPTED",
  • "paymentChannel": "PCL_CARD",
  • "actions": {
    },
  • "rejectCode": "E40199",
  • "rejectReason": "Client doesn't have enough money.",
  • "meta": {
    },
  • "customer": {
    },
  • "cardInfo": {
    },
  • "source": {
    }
}