API Reference
Go to zen.comGo to myZEN.com
Documentation
  • Sandbox
  • Plugin integration
  • Checkout integration
  • API business
  • Merchant panel
  • Brandbook
  • API transfers
Go to zen.comGo to myZEN.com
Documentation
  • Sandbox
  • Plugin integration
  • Checkout integration
  • API business
  • Merchant panel
  • Brandbook
  • API transfers
  1. purchase
  • Introduction
  • Authentication & authorization
  • Environments
  • Transaction statuses
  • Notifications
  • Response codes
  • Error codes
  • purchase
    • Create transaction
      POST
    • Capture transaction
      POST
    • Transaction details using ZEN id
      GET
    • Transaction details using merchantTransactionId
      GET
    • Cancel transaction
      POST
    • Renew authorization
      POST
    • Validate ApplePay session
      POST
    • Calculate cashback
      POST
  • refund
    • Create transaction
  • payout
    • Create transaction
    • Transaction details using ZEN id
    • Transaction details using merchantTransactionId
    • Capture transaction
    • Cancel transaction
    • Renew transaction
    • Transaction details using ZEN id
    • Refresh transaction offers
    • Select transaction offer
  • payment-methods
    • Returns information about payment methods
    • Returns information about payment methods
  • payment-links
    • Create payment link
    • Fetch payment links list
    • Fetch payment link
    • Update payment link
  • customers
    • Create customer
    • Remove customer
    • Add customer recipient
    • Add payout card
    • Remove payout card
    • Fetch payout card list
    • Update payout card details
    • Fetch saved subscription customer list V3
    • Fetch customer
    • Update a customer
    • Fetch card
    • Update card details
    • Remove card
    • Fetch card list
    • Fetch customer recipient list
    • Fetch customer recipient
    • Update customer details recipient
    • Remove customer recipient
    • Add customer payout card
    • Fetch saved payout card V3
    • Initialize widget payout card process
    • Removes customer saved payout card V3
    • Fetch saved payout card list V3
    • Fetch blik paymentTokens list
    • Remove Blik paymentToken
    • Fetch Blik paymentToken
    • Add paynow recipient
    • Remove paynow profile
    • Fetch saved merchant customer payout recipient list V3
    • Verify merchant's customer payout recipient card
    • Fetch saved merchant customer's payout card V3
    • Update merchant payout card alias
    • Removes merchant customer payout card.
  • authorization
    • Calculate authorization amount
    • Calculate reversed authorization amount
  • subscriptions
    • Fetch subscription products list
    • Add new subscription product
    • Fetch subscription product
    • Update subscription product
    • Removes subscription product
    • Fetch subscription plan list
    • Add new subscription plan
    • Fetch subscription plan
    • Removes subscription plan
    • Activate subscription plan
    • Deactivate subscription plan
    • Fetch subscriptions list
    • Fetch subscription
    • Removes subscription
    • Cancel subscription
  • reports
    • Download report file
  1. purchase

Create transaction

POST
https://api.zen.com/v1/transactions
Creates transaction. It starts the transaction process, where Merchant has to specify parameters such as the amount of transaction, currency, payment channel, transaction ID, client data etc.
Based on the provided parameters, ZEN enables the customer to make a payment. The Merchant receives notification regarding the transaction status and its details.
Please note: the transaction may have a "pending" status, because of no payment method provider final status. The Merchant should re-request the current final status of the transaction using get /v1/transactions/{id} and get /v1/transactions/merchant/{merchantTransactionId}

Request

Header Params

Body Params application/jsonRequired

Example
{
    "authorization": {
        "amount": "123.04",
        "currency": "PLN",
        "sessionId": "string",
        "type": "DIRECT"
    },
    "source": {
        "channel": "PTS_ZEN_API",
        "pluginName": "string",
        "pluginVersion": "string",
        "platformName": "string",
        "platformVersion": "string",
        "processId": "string",
        "processName": "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.g2a.com/ipn",
    "comment": "string",
    "fraudFields": {
        "property1": "string",
        "property2": "string"
    },
    "items": [
        {
            "code": "IDS123",
            "category": "cars",
            "type": "physical",
            "name": "Multipla",
            "price": "123.04",
            "quantity": 1,
            "lineAmountTotal": "123.04"
        }
    ],
    "customer": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "+48 000 000 000",
        "information": "Some information",
        "ip": "127.0.0.1"
    },
    "paymentSpecificData": {
        "browserDetails": {
            "acceptHeader": "string",
            "colorDepth": "string",
            "javaEnabled": true,
            "javascriptEnabled": true,
            "lang": "string",
            "screenHeight": "strin",
            "screenWidth": "strin",
            "timezone": "strin",
            "windowSize": "01",
            "userAgent": "string"
        },
        "threeDsData": {
            "purchase": {
                "transType": "01",
                "recurringExpiry": "20160714",
                "recurringFrequency": 9999
            },
            "cardholder": {
                "addrMatch": "Y"
            },
            "cardholderAccount": {
                "acctInfo": {
                    "chAccAgeInd": "01",
                    "chAccChange": "20160712",
                    "chAccChangeInd": "01",
                    "chAccDate": "20140328",
                    "chAccPwChange": "20170328",
                    "chAccPwChangeInd": "01",
                    "nbPurchaseAccount": "11",
                    "paymentAccAge": "20160917",
                    "paymentAccInd": "01",
                    "provisionAttemptsDay": "3",
                    "shipAddressUsage": "20160714",
                    "shipAddressUsageInd": "01",
                    "shipNameIndicator": "01",
                    "suspiciousAccActivity": "01",
                    "txnActivityDay": "1",
                    "txnActivityYear": "21"
                }
            },
            "merchantRiskIndicator": {
                "deliveryEmailAddress": "[email protected]",
                "deliveryTimeframe": "01",
                "giftCardAmount": "337",
                "giftCardCount": "02",
                "giftCardCurr": "840",
                "preOrderDate": "20170519",
                "preOrderPurchaseInd": "01",
                "reorderItemsInd": "01",
                "shipIndicator": "01"
            },
            "threeDSRequestor": {
                "threeDSRequestorAuthenticationInfo": {
                    "threeDSReqAuthData": "validlogin at UL TS BV",
                    "threeDSReqAuthMethod": "01",
                    "threeDSReqAuthTimestamp": "201711071307"
                },
                "threeDSRequestorChallengeInd": "01"
            },
            "threeDSRequestorURL": "http://example.com"
        },
        "verificationResult": {
            "errorDetails": {
                "errorCode": "101",
                "errorComponent": "C",
                "errorDescription": "Issues with certificates",
                "errorDetail": "issue with certificate",
                "errorMessageType": "AReq"
            },
            "status": "Accepted",
            "eci": "01",
            "authenticationValue": "jI3JBkkaQ1p8CBAAABy0CHUAAAA=",
            "version": "1",
            "emv3DSFlow": "ChallengeFlow",
            "directoryServerTransactionId": "673f2s39-a114-4423-b126-ffdb3a55ecfd",
            "acsTransactionId": "673f2s39-a114-4423-b126-ffdb3a55ecfd",
            "threeDSServerTransactionId": "673f2s39-a114-4423-b126-ffdb3a55ecfd",
            "amount": "12.56",
            "currency": "EUR",
            "purchaseDate": "202111142058",
            "transStatus": "Y",
            "transStatusReason": "01"
        },
        "authenticationServiceTarget": "recurring",
        "subscription": {
            "planId": "string"
        },
        "returnVerifyUrl": "https://zen.com/returnUrlAfter3ds",
        "skip3ds": true,
        "cardToken": "27a4c23c-29bb-4244-9867-0f39ecb51045",
        "descriptor": "Recuring Transaction",
        "scaExemptions": "LOW_VALUE_PAYMENT",
        "card": {
            "expiryDate": "0620",
            "cvv": 123
        },
        "type": "oneclick",
        "avsCheck": true
    },
    "billingAddress": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "country": "DE",
        "street": "Poloninska",
        "city": "Rzeszow",
        "countryState": "Utah",
        "province": "Alberta",
        "buildingNumber": "12",
        "roomNumber": "5",
        "postcode": "31-137",
        "companyName": "Mega Corp Inc.",
        "phone": "48664778234",
        "taxId": "123-45-67-890"
    },
    "shippingAddress": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "country": "DE",
        "street": "Poloninska",
        "city": "Rzeszow",
        "countryState": "Utah",
        "province": "Alberta",
        "buildingNumber": "12",
        "roomNumber": "5",
        "postcode": "31-137",
        "companyName": "Mega Corp Inc.",
        "phone": "48664778234"
    },
    "cashback": {
        "client": {
            "email": "[email protected]",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
    }
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.zen.com/v1/transactions' \
--header 'request-id;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "authorization": {
        "amount": "123.04",
        "currency": "PLN",
        "sessionId": "string",
        "type": "DIRECT"
    },
    "source": {
        "channel": "PTS_ZEN_API",
        "pluginName": "string",
        "pluginVersion": "string",
        "platformName": "string",
        "platformVersion": "string",
        "processId": "string",
        "processName": "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.g2a.com/ipn",
    "comment": "string",
    "fraudFields": {
        "property1": "string",
        "property2": "string"
    },
    "items": [
        {
            "code": "IDS123",
            "category": "cars",
            "type": "physical",
            "name": "Multipla",
            "price": "123.04",
            "quantity": 1,
            "lineAmountTotal": "123.04"
        }
    ],
    "customer": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "+48 000 000 000",
        "information": "Some information",
        "ip": "127.0.0.1"
    },
    "paymentSpecificData": {
        "browserDetails": {
            "acceptHeader": "string",
            "colorDepth": "string",
            "javaEnabled": true,
            "javascriptEnabled": true,
            "lang": "string",
            "screenHeight": "strin",
            "screenWidth": "strin",
            "timezone": "strin",
            "windowSize": "01",
            "userAgent": "string"
        },
        "threeDsData": {
            "purchase": {
                "transType": "01",
                "recurringExpiry": "20160714",
                "recurringFrequency": 9999
            },
            "cardholder": {
                "addrMatch": "Y"
            },
            "cardholderAccount": {
                "acctInfo": {
                    "chAccAgeInd": "01",
                    "chAccChange": "20160712",
                    "chAccChangeInd": "01",
                    "chAccDate": "20140328",
                    "chAccPwChange": "20170328",
                    "chAccPwChangeInd": "01",
                    "nbPurchaseAccount": "11",
                    "paymentAccAge": "20160917",
                    "paymentAccInd": "01",
                    "provisionAttemptsDay": "3",
                    "shipAddressUsage": "20160714",
                    "shipAddressUsageInd": "01",
                    "shipNameIndicator": "01",
                    "suspiciousAccActivity": "01",
                    "txnActivityDay": "1",
                    "txnActivityYear": "21"
                }
            },
            "merchantRiskIndicator": {
                "deliveryEmailAddress": "[email protected]",
                "deliveryTimeframe": "01",
                "giftCardAmount": "337",
                "giftCardCount": "02",
                "giftCardCurr": "840",
                "preOrderDate": "20170519",
                "preOrderPurchaseInd": "01",
                "reorderItemsInd": "01",
                "shipIndicator": "01"
            },
            "threeDSRequestor": {
                "threeDSRequestorAuthenticationInfo": {
                    "threeDSReqAuthData": "validlogin at UL TS BV",
                    "threeDSReqAuthMethod": "01",
                    "threeDSReqAuthTimestamp": "201711071307"
                },
                "threeDSRequestorChallengeInd": "01"
            },
            "threeDSRequestorURL": "http://example.com"
        },
        "verificationResult": {
            "errorDetails": {
                "errorCode": "101",
                "errorComponent": "C",
                "errorDescription": "Issues with certificates",
                "errorDetail": "issue with certificate",
                "errorMessageType": "AReq"
            },
            "status": "Accepted",
            "eci": "01",
            "authenticationValue": "jI3JBkkaQ1p8CBAAABy0CHUAAAA=",
            "version": "1",
            "emv3DSFlow": "ChallengeFlow",
            "directoryServerTransactionId": "673f2s39-a114-4423-b126-ffdb3a55ecfd",
            "acsTransactionId": "673f2s39-a114-4423-b126-ffdb3a55ecfd",
            "threeDSServerTransactionId": "673f2s39-a114-4423-b126-ffdb3a55ecfd",
            "amount": "12.56",
            "currency": "EUR",
            "purchaseDate": "202111142058",
            "transStatus": "Y",
            "transStatusReason": "01"
        },
        "authenticationServiceTarget": "recurring",
        "subscription": {
            "planId": "string"
        },
        "returnVerifyUrl": "https://zen.com/returnUrlAfter3ds",
        "skip3ds": true,
        "cardToken": "27a4c23c-29bb-4244-9867-0f39ecb51045",
        "descriptor": "Recuring Transaction",
        "scaExemptions": "LOW_VALUE_PAYMENT",
        "card": {
            "expiryDate": "0620",
            "cvv": 123
        },
        "type": "oneclick",
        "avsCheck": true
    },
    "billingAddress": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "country": "DE",
        "street": "Poloninska",
        "city": "Rzeszow",
        "countryState": "Utah",
        "province": "Alberta",
        "buildingNumber": "12",
        "roomNumber": "5",
        "postcode": "31-137",
        "companyName": "Mega Corp Inc.",
        "phone": "48664778234",
        "taxId": "123-45-67-890"
    },
    "shippingAddress": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "country": "DE",
        "street": "Poloninska",
        "city": "Rzeszow",
        "countryState": "Utah",
        "province": "Alberta",
        "buildingNumber": "12",
        "roomNumber": "5",
        "postcode": "31-137",
        "companyName": "Mega Corp Inc.",
        "phone": "48664778234"
    },
    "cashback": {
        "client": {
            "email": "[email protected]",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
    }
}'

Responses

🟢201Created
application/json
Transaction created
Body

Example
{
    "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-test.com/eps/image/567afec2-6189-4731-9cb3-c6d4bb4fd345/1579592876",
    "merchantAction": {
        "action": "REDIRECT",
        "data": {
            "redirectUrl": "http://example.com"
        }
    },
    "merchantTransactionId": "string",
    "originMerchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
    "amount": "123.04",
    "currency": "PLN",
    "fee": {
        "amount": "123.04",
        "currency": "EUR"
    },
    "subsidiaryData": {
        "feeAmount": "123.04",
        "grossAmount": "123.04"
    },
    "authorization": {
        "amount": "string",
        "currency": "string",
        "fee": "string"
    },
    "createdAt": "2019-08-24T14:15:22Z",
    "modifiedAt": "2019-08-24T14:15:22Z",
    "type": "TRT_REFUND",
    "status": "ACCEPTED",
    "topupTransferStatus": "ACCEPTED",
    "paymentChannel": "PCL_CARD",
    "actions": {
        "refund": false,
        "cancel": false,
        "capture": true,
        "redirect": true,
        "authorization": true,
        "selectOffer": true,
        "renewOffers": true
    },
    "fraudFields": {
        "property1": "string",
        "property2": "string"
    },
    "rejectCode": "E40199",
    "rejectReason": "Client doesn't have enough money.",
    "refunds": [
        {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "merchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
            "originMerchantTransactionId": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
            "amount": "123.04",
            "currency": "PLN",
            "createdAt": "2019-08-24T14:15:22Z",
            "status": "ACCEPTED"
        }
    ],
    "meta": {
        "payoutBtcAddress": "1HB5XDDddDDdDDDj6mfBsbifRoD4miY36v",
        "btcAmount": "10",
        "feeOwner": "partner",
        "returnUrl": "https://pay.g2a.com/checkout?",
        "customIpnUrl": "https://ipn-pay.g2a.com/ipn",
        "returnVerifyUrl": "https://zen.com/returnUrlAfter3ds",
        "avsResult": "string",
        "cvvResult": "string",
        "authorisationCode": "string",
        "resultCode": "string",
        "threeDs": {
            "xid": "string",
            "version": "string",
            "eci": "string",
            "cavv": "string",
            "cavvAlgorithm": "string",
            "emv3DSFlow": "string",
            "status": "string",
            "cardHolderInfo": "string",
            "errorData": {
                "component": "string",
                "description": "string",
                "detail": "string"
            }
        },
        "destinationCurrency": "string",
        "destinationAddress": "string",
        "destinationAddressMemo": "string",
        "travelRuleData": {
            "entityType": "individual",
            "vaspName": "string",
            "firstName": "string",
            "lastName": "string",
            "address": "string",
            "dateOfBirth": "2019-08-24"
        },
        "amountToWithdraw": "string",
        "paymentCryptoAddress": "string",
        "cryptoAmount": "string",
        "cryptoCurrencyShortName": "string",
        "cryptoCurrencyFullName": "string",
        "cryptoNetworkFee": "string",
        "tracking": "string",
        "qrCodeData": "string",
        "cryptoCurrency": "string",
        "promoCode": "string",
        "walletCurrency": "string",
        "currencyName": "string",
        "currencyCode": "string",
        "currencyLogoUrl": "string",
        "network": "string",
        "networkCode": "string",
        "networkLogoUrl": "string",
        "fundsAvailability": "string",
        "captureMode": "string"
    },
    "customer": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "+48 000 000 000",
        "information": "Some information",
        "ip": "127.0.0.1"
    },
    "cardInfo": {
        "merchantCardToken": "string",
        "bank": "Cool bank",
        "country": "DE",
        "organization": "visa",
        "organizationBrand": "debit gold",
        "token": "b5507016-7da2-4777-a161-1e8042a6a377",
        "type": "CDT_DEBIT",
        "lastFourDigits": 5516,
        "expirationDate": "2018-08-08T00:00:00.000Z",
        "bin": 557516,
        "eea": true,
        "commercial": true,
        "binRangeId": "bbf4fa18-8b09-4717-9638-45912359ba15",
        "binRangeLow": "string",
        "binRangeHigh": "string",
        "cardHolderName": "string",
        "cardHolder": {
            "firstName": "string",
            "middleName": "string",
            "lastName": "string",
            "birthDate": "string"
        }
    },
    "paymentToken": "string",
    "billingAddress": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "country": "DE",
        "street": "Poloninska",
        "city": "Rzeszow",
        "countryState": "Utah",
        "province": "Alberta",
        "buildingNumber": "12",
        "roomNumber": "5",
        "postcode": "31-137",
        "companyName": "Mega Corp Inc.",
        "phone": "48664778234",
        "taxId": "123-45-67-890"
    },
    "shippingAddress": {
        "id": "23beb187-f8a3-44b8-9ef8-b31180358dd3",
        "firstName": "John",
        "lastName": "Doe",
        "country": "DE",
        "street": "Poloninska",
        "city": "Rzeszow",
        "countryState": "Utah",
        "province": "Alberta",
        "buildingNumber": "12",
        "roomNumber": "5",
        "postcode": "31-137",
        "companyName": "Mega Corp Inc.",
        "phone": "48664778234"
    },
    "items": [
        {
            "code": "IDS123",
            "category": "cars",
            "type": "physical",
            "name": "Multipla",
            "price": "123.04",
            "quantity": 1,
            "lineAmountTotal": "123.04"
        }
    ],
    "verifyReturnmac": "7e92079c-79e1-47bd-af9d-80c2f7783037",
    "cashback": {
        "active": false,
        "values": [
            {
                "type": "PERCENT",
                "value": "string"
            }
        ],
        "client": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "type": "string",
            "tenantId": 101,
            "email": "[email protected]"
        }
    },
    "source": {
        "pluginName": "string",
        "pluginVersion": "string",
        "platformName": "string",
        "platformVersion": "string",
        "processId": "string",
        "processName": "string"
    }
}
🟠404Record Not Found
Modified at 2025-11-10 07:13:37
Previous
Error codes
Next
Capture transaction