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 terminalId 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
    terminalId: string Y In order to obtain terminalId:
    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 terminalId 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 N First name of the buyer
    customer[lastName]: string <= 128 characters N 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 N Name of the sold item
    items[0][price]: string^-?(?=.*[1-9])\d{1,16}(?:\.\d{1,12})?$ N Unit price of the sold item
    items[0][quantity]: number N Quantity of the sold items
    items[0][lineAmountTotal]: string^-?(?=.*[1-9])\d{1,16}(?:\.\d{1,12})?$ N Total price of the sold items
    version: 1.0.0;form Version of the Paywall
    signature: Signature of the post
    1. Form data example:

      terminalId: 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
      version: 1.0.0;form
      signature: 479acd1858e991b7aeba39ed9f7d7a288a3bb739a07e1a0e32fa9e5bafea0ff8;sha256

    2. Example of a form POST:

      terminalId=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&version=1.0.0%3Bform&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< serviceKey>);

    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).