API Reference
Go to zen.comGo to myZEN.com
Documentation
  • Plugin integration
  • Checkout integration
  • API business
  • Merchant panel
Brandbook
Go to zen.comGo to myZEN.com
Documentation
  • Plugin integration
  • Checkout integration
  • API business
  • Merchant panel
Brandbook
  1. payout
  • Introduction
  • Authentication & authorization
  • Environments
  • Transaction statuses
  • Notifications
  • Response codes
  • Error codes
  • purchase
    • Create transaction
    • Capture transaction
    • Transaction details using ZEN id
    • Transaction details using merchantTransactionId
    • Cancel transaction
    • Renew authorization
    • Validate ApplePay session
    • Calculate cashback
  • refund
    • Create transaction
  • payout
    • Create transaction
      POST
    • Transaction details using ZEN id
      GET
    • Transaction details using merchantTransactionId
      GET
    • Capture transaction
      POST
    • Cancel transaction
      POST
    • Renew transaction
      POST
    • Transaction details using ZEN id
      GET
    • Refresh transaction offers
      POST
    • Select transaction offer
      POST
  • 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
    • Fetch saved merchant customer payout recipient list V3
    • Verify merchant's customer payout recipient card
    • Fetch saved merchant customer's payout card V3
    • Initialize widget payout card process
    • Update merchant payout card alias
    • Fetch saved payout card list V3
    • Removes merchant customer payout card.
    • Add customer payout card
    • Fetch saved payout card V3
    • Removes customer saved payout card V3
    • Add paynow recipient
    • Remove paynow profile
  • 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. payout

Transaction details using merchantTransactionId

GET
https://api.zen.com/v1/payouts/merchant/{merchantTransactionId}
payout
Allows to get payout details using Merchant transaction ID. Only one created payout can be get each time. It can be fetch all payout data including: ID, parent transaction ID, URL, amount, currency, customers, fees, authorization amount, status and many more.

Request

Path Params
merchantTransactionId
string 
required
An unique merchant transaction identifier
>= 1 characters<= 128 characters
Example:
23beb187-f8a3-44b8-9ef8-b31180358dd3
Match pattern:
^[a-zA-Z0-9?&:\-\/=.,#|+_$\[\]€ ]+$
Header Params
request-id
string 
required
A unique identifier generated by requesting client
>= 38 characters<= 1024 characters
Example:
|us04oqdnzFQVr0rITD9/c9OvDRE2sXVfwerv.
Match pattern:
^[a-zA-Z0-9?&:_|\-\/=+.,#\s]+$

Request 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 GET 'https://api.zen.com/v1/payouts/merchant/' \
--header 'request-id;'

Responses

🟢200OK
application/json
OK
Body
id
string <uuid>
optional
parentTransactionId
string <uuid>
optional
redirectUrl
string <uri>
optional
Redirect url provided by PSP. If "actions" states it, buyer should be redirected to this url in order to proceed with payment
<= 256 characters
Example:
https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=
imageUrl
string <uri>
optional
Image url after successul payment initialization (e.g., for QR code payment).
<= 256 characters
Example:
https://notifications.zen-test.com/eps/image/567afec2-6189-4731-9cb3-c6d4bb4fd345/1579592876
merchantAction
optional
One of
Example:
{"action":"REDIRECT","data":{"redirectUrl":"https://redirect-service.com/redirect"}}
action
enum<string> 
required
Allowed value:
REDIRECT
data
object 
required
merchantTransactionId
string 
required
Merchant transaction Id. Sould be unique in merchant store.
originMerchantTransactionId
string 
optional
Origin Id of the transaction provided by merchant.
>= 1 characters<= 128 characters
Example:
23beb187-f8a3-44b8-9ef8-b31180358dd3
amount
string 
required
Amount of the transaction.
Example:
123.04
Match pattern:
^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$
currency
string 
required
Currency code in ISO 4217 alphabetic code
>= 3 characters<= 3 characters
Example:
PLN
Match pattern:
^[A-Z]+$
fee
object 
Transaction fee
optional
amount
string 
required
Amount of the transaction.
Example:
123.04
Match pattern:
^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$
currency
string 
required
Currency of the amount specified in the amount property.
>= 3 characters<= 3 characters
Example:
EUR
subsidiaryData
object  | null 
optional
feeAmount
string 
required
Amount of the transaction.
Example:
123.04
Match pattern:
^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$
grossAmount
string 
required
Amount of the transaction.
Example:
123.04
Match pattern:
^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$
authorization
object 
optional
amount
string 
required
currency
string 
required
fee
string 
optional
createdAt
string <date-time>
required
modifiedAt
string <date-time>
required
type
string 
required
Type of transaction
Example:
TRT_REFUND
Match pattern:
^TRT(_[A-Z0-9]+)+$
status
enum<string> 
transaction status
required
Transaction status
Allowed values:
ACCEPTEDPENDINGAUTHORIZEDCANCELEDREJECTED
topupTransferStatus
enum<string> 
topup transfer status
optional
Topup transfer status
Allowed values:
ACCEPTEDPENDINGREJECTED
paymentChannel
string 
optional
Id of the payment channel for selected payment method.
Example:
PCL_CARD
Match pattern:
^([a-z](-?[a-z0-9])*|[A-Z](_?[A-Z0-9])*)$
actions
object 
Combined payment methods information
optional
Defines acctions that can be made for transaction
refund
boolean 
optional
Example:
false
cancel
boolean 
optional
Example:
false
capture
boolean 
optional
Example:
true
redirect
boolean 
optional
Example:
true
authorization
boolean 
optional
Example:
true
selectOffer
boolean 
optional
Example:
true
renewOffers
boolean 
optional
Example:
true
fraudFields
object  | null 
optional
Field used for fraud dedection system
Additional properties
optional
rejectCode
string 
optional
Example:
E40199
Match pattern:
^[A-Z0-9]+$
rejectReason
string 
optional
Example:
Client doesn't have enough money.
refunds
array[object (Details about refund transaction) {7}] 
optional
id
string <uuid>
required
merchantTransactionId
string 
required
>= 1 characters<= 128 characters
Example:
23beb187-f8a3-44b8-9ef8-b31180358dd3
Match pattern:
^[a-zA-Z0-9?&:\-\/=.,#]+$
originMerchantTransactionId
string 
optional
Origin Id of the transaction provided by merchant.
>= 1 characters<= 128 characters
Example:
23beb187-f8a3-44b8-9ef8-b31180358dd3
amount
string 
required
Amount of the transaction.
Example:
123.04
Match pattern:
^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$
currency
string 
required
Currency code in ISO 4217 alphabetic code
>= 3 characters<= 3 characters
Example:
PLN
Match pattern:
^[A-Z]+$
createdAt
string <date-time>
optional
status
enum<string> 
transaction status
optional
Transaction status
Allowed values:
ACCEPTEDPENDINGAUTHORIZEDCANCELEDREJECTED
meta
object 
optional
payoutBtcAddress
string 
optional
Payout Address
>= 25 characters<= 36 characters
Example:
1HB5XDDddDDdDDDj6mfBsbifRoD4miY36v
Match pattern:
^[13][a-km-zA-HJ-NP-Z1-9]{25,34}$
btcAmount
string 
optional
btc Amount
<= 128 characters
Example:
10
feeOwner
enum<string> 
optional
Payout transaction fee owner
Allowed value:
partner
Example:
partner
returnUrl
string <uri>
optional
Return url after successul payment. (Will override defualt shop settings)
<= 1024 characters
Example:
https://pay.g2a.com/checkout?
customIpnUrl
string <uri>
optional
URL address used by ZEN to send IPN to
<= 1024 characters
Example:
https://ipn-pay.g2a.com/ipn
returnVerifyUrl
string <uri>
optional
Return URL after 3DS authentiaction
<= 1024 characters
Example:
https://zen.com/returnUrlAfter3ds
avsResult
string 
optional
cvvResult
string 
optional
authorisationCode
string 
optional
resultCode
string 
optional
threeDs
object 
optional
destinationCurrency
string 
optional
destinationAddress
string 
optional
destinationAddressMemo
string 
optional
travelRuleData
optional
amountToWithdraw
string 
optional
paymentCryptoAddress
string 
optional
cryptoAmount
string 
optional
cryptoCurrencyShortName
string 
optional
cryptoCurrencyFullName
string 
optional
cryptoNetworkFee
string 
optional
tracking
string 
optional
qrCodeData
string 
optional
cryptoCurrency
string 
optional
promoCode
string 
optional
<= 256 characters
walletCurrency
string  | null 
optional
currencyName
string  | null 
optional
currencyCode
string  | null 
optional
currencyLogoUrl
string  | null 
optional
network
string  | null 
optional
networkCode
string  | null 
optional
networkLogoUrl
string  | null 
optional
fundsAvailability
string  | null 
optional
captureMode
string  | null 
optional
customer
object 
optional
id
string 
optional
Customer's ID as provided by the merchant
<= 64 characters
Example:
23beb187-f8a3-44b8-9ef8-b31180358dd3
segment
string 
optional
Client segment
Example:
CSG_CREATIVE
firstName
string 
optional
Customer's firstname
<= 128 characters
Example:
John
lastName
string 
optional
Customer's lastname
<= 128 characters
Example:
Doe
email
string <email>
required
Customer's email
<= 256 characters
Example:
[email protected]
phone
string 
optional
Customer's phone number
<= 64 characters
Example:
+48 000 000 000
information
string 
optional
Some information about customer
<= 128 characters
Example:
Some information
ip
optional
cardInfo
object 
Transaction card info
optional
merchantCardToken
string 
optional
Token of merchant card
bank
string 
optional
Name of bank issuing the payment card.
Example:
Cool bank
country
string 
optional
Country code
>= 2 characters<= 2 characters
Example:
DE
Match pattern:
^[A-Z]+$
organization
string 
optional
Name of the payment card organization.
Example:
visa
organizationBrand
string 
optional
Brand of the payment card.
Example:
debit gold
token
string <uuid>
optional
Card profile token
segment
string 
optional
Card segment
Example:
CSG_INDIVIDUAL
type
string 
optional
Card type
Example:
CDT_DEBIT
lastFourDigits
string 
optional
The last four digits of a payment card number.
>= 4 characters<= 4 characters
Example:
5516
expirationDate
string <date>
optional
The payment card expiration date.
Example:
2018-08-08T00:00:00.000Z
bin
string 
optional
The first six digits of a payment card number.
>= 6 characters<= 11 characters
Example:
557516
eea
boolean 
optional
Indicates card come from EEA.
commercial
boolean 
optional
Indicates card is commercial
binRangeId
string <uuid>
optional
BinChecker's id
binRangeLow
string 
optional
BinChecker's low value
binRangeHigh
string 
optional
BinChecker's high value
cardHolderName
string 
deprecated
CardHolder name
cardHolder
object 
optional
Cardholder data
paymentToken
string 
Transaction payment token
optional
billingAddress
object 
optional
id
string 
optional
Customer's ID as provided by the merchant
<= 64 characters
Example:
23beb187-f8a3-44b8-9ef8-b31180358dd3
segment
string 
optional
Client segment
Example:
CSG_CREATIVE
firstName
string 
optional
Customer's firstname
<= 128 characters
Example:
John
lastName
string 
optional
Customer's lastname
<= 128 characters
Example:
Doe
country
string 
optional
Country code
>= 2 characters<= 2 characters
Example:
DE
Match pattern:
^[A-Z]+$
street
string 
optional
Street name
<= 128 characters
Example:
Poloninska
city
string 
optional
City name
<= 128 characters
Example:
Rzeszow
countryState
string 
optional
Country state
<= 128 characters
Example:
Utah
province
string 
optional
Province name
<= 128 characters
Example:
Alberta
buildingNumber
string 
optional
Building number
<= 128 characters
Example:
12
roomNumber
string 
optional
Room number
<= 32 characters
Example:
5
postcode
string 
optional
Post code
>= 1 characters<= 10 characters
Example:
31-137
Match pattern:
^[a-zA-Z0-9\s\-]+$
companyName
string 
optional
Company name
<= 128 characters
Example:
Mega Corp Inc.
phone
string 
optional
Phone number
>= 2 characters<= 64 characters
Example:
48664778234
Match pattern:
^[0-9\+]+$
taxId
string 
optional
<= 128 characters
Example:
123-45-67-890
Additional properties
integer  | number  | string  | boolean 
optional
shippingAddress
object 
optional
id
string 
optional
Customer's ID as provided by the merchant
<= 64 characters
Example:
23beb187-f8a3-44b8-9ef8-b31180358dd3
segment
string 
optional
Client segment
Example:
CSG_CREATIVE
firstName
string 
optional
Customer's firstname
<= 128 characters
Example:
John
lastName
string 
optional
Customer's lastname
<= 128 characters
Example:
Doe
country
string 
optional
Country code
>= 2 characters<= 2 characters
Example:
DE
Match pattern:
^[A-Z]+$
street
string 
optional
Street name
<= 128 characters
Example:
Poloninska
city
string 
optional
City name
<= 128 characters
Example:
Rzeszow
countryState
string 
optional
Country state
<= 128 characters
Example:
Utah
province
string 
optional
Province name
<= 128 characters
Example:
Alberta
buildingNumber
string 
optional
Building number
<= 128 characters
Example:
12
roomNumber
string 
optional
Room number
<= 32 characters
Example:
5
postcode
string 
optional
Post code
>= 1 characters<= 10 characters
Example:
31-137
Match pattern:
^[a-zA-Z0-9\s\-]+$
companyName
string 
optional
Company name
<= 128 characters
Example:
Mega Corp Inc.
phone
string 
optional
Phone number
>= 2 characters<= 64 characters
Example:
48664778234
Match pattern:
^[0-9\+]+$
items
array [object {7}] 
optional
If items are provided sum of items amount should be equal transaction amount
code
string  | null 
optional
Item code
<= 64 characters
Example:
IDS123
category
string  | null 
optional
Item category
<= 64 characters
Example:
cars
type
enum<string> 
optional
Allowed values:
physicaldigital
Example:
physical
name
string  | null 
required
Item Name
<= 256 characters
Example:
Multipla
price
string 
required
Unit price of the item
Example:
123.04
Match pattern:
^-?(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$
quantity
number 
required
Item quantity
>= 1
Example:
1
lineAmountTotal
string 
required
Price multiplied by quantity
Example:
123.04
Match pattern:
^-?(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$
verifyReturnmac
string <uuid>
optional
cashback
object 
optional
Information about transaction cashback.
active
boolean 
optional
Default:
false
values
array [object {2}] 
optional
client
object 
optional
Information about cashback client.
source
object 
optional
channel
string 
required
<= 32 characters
Default:
PTS_ZEN_API
pluginName
string 
optional
<= 32 characters
pluginVersion
string 
optional
<= 16 characters
platformName
string 
optional
<= 32 characters
platformVersion
string 
optional
<= 16 characters
processId
string 
optional
processName
string 
optional
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",
        "segment": "CSG_CREATIVE",
        "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",
        "segment": "CSG_INDIVIDUAL",
        "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",
        "segment": "CSG_CREATIVE",
        "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",
        "segment": "CSG_CREATIVE",
        "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": {
        "channel": "PTS_ZEN_API",
        "pluginName": "string",
        "pluginVersion": "string",
        "platformName": "string",
        "platformVersion": "string",
        "processId": "string",
        "processName": "string"
    }
}
🟠404Record Not Found
Modified at 2025-07-10 11:28:41
Previous
Transaction details using ZEN id
Next
Capture transaction