Paywall Direct Integration

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 the integration process and introduce the main features of the Paywall integration.

Paywall transactions are made by posting form data (described below) to checkout.zen.com/payment.

  1. Allowed HTTPs requests

  2. Credentials required to use Paywall integration

    Name Description
    Terminal UUID To start using ZEN Paywall user needs to be able to authorize his requests. It is done by adding a Terminal UUID key to the request header. In order to retrieve your Terminal UUID please:
    1. Login to ZEN account
    2. Open menu and go to Store settings in the Sell online section
    3. Visit API & Documentation section
    4. Terminal UUID corresponds with terminalUuid used in the paywall integration
    Paywall Secret To create POST signature, the user needs to use Paywall secret. In order to retrieve it:
    1. Login to ZEN account
    2. Open menu and go to Store settings in the Sell online section
    3. Visit API & Documentation section
    4. Copy Paywall secret
    IPN Secret IPN (Instant Payment Notification) notifies user about the status of transaction. In order to verify whether IPN is authorized by ZEN user needs an IPN secret. In order to retrieve it:
    1. Login to ZEN account
    2. Open menu and go to Store settings in the Sell online section
    3. Visit API & Documentation section
    4. Copy IPN secret
  3. Form data fields

    In order to create a checkout user should POST proper form data to ZEN. Below table covers description of the form data fields.

    Name Allowed values Required field Description
    terminalUuid: string Y In order to obtain terminalUuid:
    1. Login to ZEN account
    2. Open menu and go to Store settings in the Sell online section
    3. Visit API & Documentation section
    4. Terminal UUID corresponds with terminalUuid used in the paywall integration
    amount: string^(?=.*[0-9])\d{1,16}(?:\.\d{1,12})?$ Y Amount of the transaction
    currency: string 3 characters Y Currency of the transaction (it will determine payment methods displayed on the paywall)
    merchantTransactionId: string [ 1 .. 128 ] characters ^[a-zA-Z0-9?&:\-\/=.,#]+$ Y Merchant’s unique identifier of the transaction
    customer[firstName]: string <= 128 characters Y First name of the buyer
    customer[lastName]: string <= 128 characters Y Last name of the buyer
    customer[email]: string <= 256 characters Y Email address of the buyer
    items[0][code]: string <= 64 characters N Merchant’s code for the sold item
    items[0][category]: string <= 64 characters N Merchant’s category for the sold item
    items[0][name]: string <= 128 characters Y Name of the sold item
    items[0][price]: string^-?(?=.*[1-9])\d{1,16}(?:\.\d{1,12})?$ Y Unit price of the sold item
    items[0][quantity]: number Y Quantity of the sold items
    items[0][lineAmountTotal]: string^-?(?=.*[1-9])\d{1,16}(?:\.\d{1,12})?$ Y Total price of the sold items
    signature: Y Signature of the post
    shippingAddress[id] string <= 64 characters ^[a-zA-Z0-9_-]+$ N This is ID of the merchant's customer provided by merchant
    shippingAddress[firstName] string <= 128 characters N First name of the buyer
    shippingAddress[lastName] string <= 128 characters N Last name of the buyer
    shippingAddress[country] string 2 characters ^[A-Z]+$ N Country of the buyer
    shippingAddress[street] string <= 128 characters N Street of the buyer
    shippingAddress[city] string <= 128 characters N City of the buyer
    shippingAddress[countryState] string <= 128 characters N Country state of the buyer
    shippingAddress[province] string <= 128 characters N Province of the buyer
    shippingAddress[buildingNumber] string <= 32 characters N Building number of the buyer
    shippingAddress[roomNumber] string <= 32 characters N Room number of the buyer
    shippingAddress[postcode] string [ 5 .. 6 ] characters N Postcode of the buyer
    shippingAddress[companyName] string <= 128 characters N Company name of the buyer
    shippingAddress[phone] string [ 2 .. 64 ] characters ^[0-9\+]+$ N Phone of the buyer
    billingAddress[id] string <= 64 characters ^[a-zA-Z0-9_-]+$ N This is ID of the merchant's customer provided by merchant.
    billingAddress[firstName] string <= 128 characters N First name of the buyer
    billingAddress[lastName] string <= 128 characters N Last name of the buyer
    billingAddress[country] string 2 characters ^[A-Z]+$ N Country of the buyer
    billingAddress[street] string <= 128 characters N Street of the buyer
    billingAddress[city] string <= 128 characters N City of the buyer
    billingAddress[countryState] string <= 128 characters N Country state of the buyer
    billingAddress[province] string <= 128 characters N Province of the buyer
    billingAddress[buildingNumber] string <= 32 characters N Building number of the buyer
    billingAddress[roomNumber] string <= 32 characters N Room number of the buyer
    billingAddress[postcode] string [ 5 .. 6 ] characters N Postcode of the buyer
    billingAddress[companyName] string <= 128 characters N Company name of the buyer
    billingAddress[phone] string [ 2 .. 64 ] characters ^[0-9\+]+$ N Phone of the buyer
    billingAddress[taxId] string <= 128 characters N Tax Id of the buyer
    successUrl string <= 256 characters url N Success URL
    failureUrl string <= 256 characters url N Failure URL
    returnUrl string <= 256 characters url N Return URL
    customIpnUrl string <= 256 characters url N Custom IPN URL
    1. Form data example:

      terminalUuid: FF7C0356-AF09-4988-9F14-EB11BC682112
      amount: 100
      currency: PLN
      merchantTransactionId: 163e9f97-2271-4f3d-922a-4a2bcaa47560
      customer[firstName]: John
      customer[lastName]: Doe
      customer[email]: [email protected]
      items[0][code]: IDS123
      items[0][category]: category
      items[0][name]: Multipla
      items[0][price]: 100
      items[0][quantity]: 1
      items[0][lineAmountTotal]: 100
      signature: 479acd1858e991b7aeba39ed9f7d7a288a3bb739a07e1a0e32fa9e5bafea0ff8;sha256

    2. Example of a form POST:

      terminalUuid=FF7C0356-AF09-4988-9F14-EB11BC682112&amount=100¤cy=PLN&merchantTransactionId=469cf1b7-53a4-47c4-8324-5ad549954dd6&customer%5BfirstName%5D=John&customer%5BlastName%5D=Doe&customer%5Bemail%5D=john%40doe.pl&items%5B0%5D%5Bcode%5D=IDS123&items%5B0%5D%5Bcategory%5D=category&items%5B0%5D%5Bname%5D=Multipla&items%5B0%5D%5Bprice%5D=100&items%5B0%5D%5Bquantity%5D=1&items%5B0%5D%5BlineAmountTotal%5D=100&signature=abb1fcaa93efaf00763693fdfc5061f5fb0023e6006f3704b1feecf0fe16c332%3Bsha256

  4. Creating signature

    In order to verify received form-data belongs to authorized merchant ZEN verifies signature of the received POST. Signature is created using example presented below and hashing it using sha224, sha256, sha384, sha512 algorithm, all fields are sorted alphabetically:

    signature = signatureAlgorithm(key1=val1&key2=val2&...&keyN=valN< paywallSecret>);

    Signature generation example:

    sha256(key1=val1&key2=val2&...&keyN=valN5cb0d6819386637557d1e8b1075450db);sha256

  5. IPN API Secrets

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

    Instant payment notification object:

    {
     type: string;
     transactionId: string;
     merchantTransactionId: string;
     amount: string;
     currency: string;
     status: string;
     orderCreatedAt?: string;
     orderCompleteAt?: string;
     refundedAmount?: number;
     provisionAmount?: number;
     hash: string;
     paymentMethod: {
      pspId: string;
      name: string;
      channel: string;
      parameters?: {[key: string]: string};
     }
     processingTime?: boolean;
     customer: {
      id?: string;
      firstName?: string;
      lastName?: string;
      email: string;
      phone?: string;
      accountId?: string;
      ip: string;
      country: string;
     }
     securityStatus?: string;
     sendPush?: number;
     isCash?: boolean;
     email?: string;
     riskData?: {[key: string]: string | object};
     hasRecurringShield?: number;
     includedFeeVat?: string;
     ssRequestId?: string;
     cardToken?: string;
    }

    hash = sha256( )

Paywall Settings

Once redirected to ZEN Paywall buyer will be presented with payment methods allowed to process currency of the transaction. You can further manage the list of allowed payment methods by logging into your ZEN account and selecting Store settings from the main menu. Payment methods page includes a list of all payment methods configured on your paywall. By clicking on any of the icons you can turn in on (color) or off (grayed out).