This page explains the different steps to configure a new Zuora tenant.

General information

Zuora has 2 datacenters : 

EU and US

Hotel-Spider CH is hosted in the US Datacenter

Hotel-Spider DE is hosted in the EU Datacenter

We use the REST interface. Previously the code was based on SOAP but it is not available in the EU Datacenter !

The REST documentation can be found at https://www.zuora.com/developer/api-reference/

REST endpoints

We authentify the system using the HTTP Headers apiAccessKeyId and apiSecretAccessKey.

Prequired

An access to the Zuora extranet with a user that has administrator role.

Note : If we want to use the same email on different tenants, we need to use an "alias". Example : firstname.lastname+de@hotel-spider.com

Every steps in this page supposes you are logged as an administrator in the corresponding Zuora extranet.

Make sure Zuora has activated all same modules as our Swiss account. Example : Owner Transfer Amendment

Data synchronisation

API User

User role

Go to Settings > Administation > Manage User Roles

Add new role :

IP Restriction

Add the staging and production IP

User API

Go to Settings > Administration > Manage Users

Click on Add single user.

For the user email, user an alias with a + :

example : dev+germany@hotel-spider.ch

For the work email, do not add the +alias

Store password and secret in Lastpass !

DO NOT ENABLE TWO-FACTOR AUTH!

To setup the password, you need to allow tempoarly your current IP for API USERS or you won't be able to set the passsword!

Security Policies

go to Settings > Administration > Setting Security Policies

Billing Settings

Default Subscription Settings

Manage Custom Fields

Go to Settings > Billing > Manage Custom Fields

Note: when configuring the fields, DO NOT ADD the __c at the end, Zuora will do it after saving.

We use the following 2 types of data : Text and Picklist. Text fields have a maxlength indicated with a number in parentheses.

Custom fields can be Indexed or not

Account Fields (Indexed)

Product Fields (Indexed)

Product Fields (Non-Indexed)

Product Rate Plan Fields (Indexed)

Product Rate Plan Fields (Non-Indexed)

Product Rate Plan Charges Fields (Non-Indexed)

Subscription Rate Plan Fields (Non-Indexed)

Amendment Fields (Non-indexed

Define Billing Periods

Customize Billing Periods

Tourisoft Sàrl:

• Month (default)
• Quarter
• Semi-Annual
• Annual

all Tourisoft Sàrl products are to be defined prioritarily in monthly, as customers are required to pay monthly fees. The quarter, semi-annual, annual are active for specific products, for swiss clients until direct debit is made available. Some African customers also may optionally benefit from this as they have high banking fees and very slow and complicated banking transactions.

Tourisoft GmbH:

• Month (default)

Customize Billing Day

Default from Customer Account

Customize Billing Period Start Days

1st of the month

Customize List Price Base

Billing period

Billing Rules

Define Numbering and SKU Formats

Enable Charge Types / Models

Customize Payment terms

Go to Settings > Billing > Customize Payment Terms

Add and activate the following payments : net10 and net30. (do not write Net30 !!!)

As per request of certain customers, net0 has been added (upon receipt)

Setup Taxation Code

use the import file (CSV) TaxRates_Import_File.csv

One separate file for each tenant

Tourisoft Sàrl:

• Swiss VAT (7.7%) - as of 01.01.2018 - insert 0.077 in column G under Switzerland

Tourisoft GmbH:

• German VAT (19%) - insert 0.19 in column G under Germany

Payment Settings

Customize Payment Methods

Define the payment methods that your organization accepts

Active	Name	Accounting Code
ACH Cash Check Credit Card PayPal Wire Transfer Debit Card CC Reference Transaction Bank Transfer Other		Accounting Codes for Payments and Refunds can be configured inFinance Settings: Configure Accounting Codes.

Payment Gateways

Tourisoft Sàrl:

Name	Gateway	Active	Actions
Adyen Gateway	Adyen		[Edit] Default
My Hateway	Test Gateway		[Edit] [Activate]
AdyenCHF	Adyen		[Edit] [Make Default] [Deactivate]

At Adyen, specific API user accounts must be created and connected with to Zuora (to create Adyen doc)

Tourisoft Gmbh (to be completed)

Setup profiles, Notifications and Email Templates

define as needed (to develop)

Configure Payment Retry Rules

Enable the functionality.

A good standard is 2 retries per 24 hours interval

Setup Payment Method Updater

not used at the moment

Setup Hosted Pages

not used at the moment

Manage Custom Fields

No Payment custom fields at the moment

Configure Reason Codes

By default all active for the moment. To be developed

Finance Settings

Manage Custom Fields

no finance custom fields at the moment

Configure Aging Balance Settings

Configure Accounting Codes

Make sure each item has the corresponding debit/ credit accounting code. Very specific to the situation

Configure Accounting Rules

	Allow blank Accounting Codes
	Allow Subscription and Amendments to be created in a closed Accounting Period
	Allow Usage to be created in a closed Accounting Period
	Allow Revenue Schedules to have negative amounts in the Open-Ended Accounting Period

Setup Profiles, Notifications and Email Templates

setup accordingly (for finance email by default)

Set Revenue Automation Start Date

Enable once revenue recognition may be started (make sure all settings are set-up)

Configure Revenue Event Types

Label System ID Active Actions Accounting Period(s) Created AccountingPeriodsCreated__z [Edit]    Invoice Cancelled InvoiceCancelled__z [Edit]    Invoice Item Adjustment Cancelled InvoiceItemAdjustmentCancelled__z [Edit]    Invoice Item Adjustment Created InvoiceItemAdjustmentCreated__z [Edit]    Invoice Posted InvoicePosted__z [Edit]    Revenue Distributed RevenueDistributed__z [Edit]

Manage Revenue Recognition Rules

Revenue Recognition Rule	Recognition Model	Active	Actions
Monthly recognition over time	Billing - Monthly recognition over time		[Edit]   [Deactivate]
Recognize upon invoicing	Billing - Full recognition upon invoicing		[Edit]   [Deactivate]

To be elaborated as we connect to potential ERPs?

Segments

Object	Field	Segment Name	System ID	Actions
Account	Market__c	Account Market	AccountMarket__s	[Edit]   [Remove]

Additional Configurations

	Discount segment value
	Invoice owner segment value
	Revenue owner segment value

Configure GL Segmentation Rules

by default AccountMarketSegment

to be furhter developped

Manage Chart of Accounts

Accounting Code Name	Accounting Code Type	Active	Actions
Accounts Receivable	Assets: Accounts Receivable		[Edit]   [Deactivate]
Bank	Assets: Cash		[Edit]   [Deactivate]
Cash	Assets: Cash		[Edit]   [Deactivate]
Credit Card	Assets: Cash		[Edit]   [Deactivate]
Customer Cash on Account	Liabilities: Customer Cash on Account		[Edit]   [Deactivate]
Deferred Revenue	Liabilities: Deferred Revenue		[Edit]   [Deactivate]
Sales Tax Payable	Liabilities: Sales Tax Payable		[Edit]   [Deactivate]
Callback Authentication Revenue	Revenue: Sales Revenue		[Edit]   [Deactivate]
Central Reservation System Revenue	Revenue: Sales Revenue		[Edit]   [Deactivate]
Direct Subscription Revenue	Revenue: Sales Revenue		[Edit]   [Deactivate]
Discounts	Revenue: Sales Discounts		[Edit]   [Deactivate]
FAX Notification Revenue	Revenue: Sales Revenue		[Edit]   [Deactivate]
Negotiated Contracts Revenues	Revenue: Sales Revenue		[Edit]   [Deactivate]
SMS Authentication Revenue	Revenue: Sales Revenue		[Edit]   [Deactivate]
White Label Revenue	Revenue: Sales Revenue		[Edit]   [Deactivate]
Write Off	Expenses: Bad Debt		[Edit]   [Deactivate]

Batch

Bill runs

Charge types

Go to Settings > Billing > Enable Charge Types / Models

Check all charge models

Product Catalog

To be completed

Notification / Callouts configuration

Go to Settings > Billing > Setup Profiles, Notifications and Email Templates 

First of all, disable ALL email callouts.

Invoices

Invoices net10 vs net30

The invoice due date is different based on the payment term :

Invoices callout parameters

New Subscription

?type=NewSubscription

A new subscription has been created and activated.

Amendments

Cancellation

A subscription cancellation amendment has been submitted and processed.

?type=Cancellation

New product

An add new product amendment has been submitted and processed.

?type=NewProduct

Update Product

An update product amendment has been submitted and processed.

?type=UpdateProduct

Payments

Payment declined 

First Attempt

?type=PaymentDeclined

The payment was declined by the payment gateway upon the first attempt.

Payment processed 

The payment was processed successfully.

?type=PaymentProcessed

Payment expiration

30 Day Warning

 ?type=PaymentExpiration30Days

The credit card set as the default payment method on the account is within 30 days of expiration.

Database

Accounts are idenfitied by the field ZuoraTenantId of type INT in the tables

group.dbo.Hotels

v4.dbo.Affiliations

v4.dbo.whitelabels

Tenants are stored in the table [v4].[dbo].[ZuoraTenants]

• username and password are the credentials for the API user
  • Password in database is encrypted

  • \Tools::encrypt('password');

• tenantId is the tenantId in the v4
• UOMMapping is used to map the UOMs. this is really helpfull for tenants that have anoying tabulations or spaces

  • {"duplicatechannels":"Duplicate Channels","bookingchannels":"Booking Channels","reservationamount":"Reservation Amount ","reservationcount":"Reservations"}

• Name is the name of the tenant
• InvoiceTemplates is the invoice template mapping in JSON format. example:

  • [{"name":"hotel_de","id":"8adc8f9968a1c7d60168a41c7e92567e","language":"de","type":"hotel"},{"name":"whitelabel_de","id":"8adc8f9968a1c7d60168a41c7e92567e","language":"de","type":"whitelabel"}]

• ZuoraCurrencyCodes : the currencies the tenant support. Separated by commas
• Endpoint is the base URL for the tenant

Tenant affecation for whitelabels are set in [v4].[dbo].[ZuoraWhitelabelTenant]. This table store the product catalog for a specific whitelabel on a tenant and also declare the default invoice template Id to use

Catalog importation

Open a SSH to a production machine and execute 

 php /var/www/cron/ZuoraProductCatalog.php

Tests

Add a new hotel by selecting the new tenant as destination and add a subscription to it.