> [!CAUTION]
> **Caution:** This documentation covers Edge for Private Cloud 4.51.00, which is no longer supported. Google does not provide security patches, bug fixes, or technical support for this version. The current supported version is 4.54.00. See the [Edge for Private Cloud documentation](https://docs.apigee.com/private-cloud/latest/overview) for the current version, or [All versions](https://docs.apigee.com/private-cloud/versions) to compare releases.

Monetization Services is an extension to Apigee Edge, hence it does not run as a standalone
process. It runs within any existing Apigee Edge setup, with the exception of the All-In-One (AIO)
configuration. You cannot install Monetization Services on an AIO configuration.

## Monetization requirements

- If you are installing Monetization on an Edge topology that uses multiple Management Server nodes, such as a 13-node installation, then you must install both Edge Management Server nodes before installing Monetization.
- To install Monetization on Edge where the Edge installation has multiple Postgres nodes, the Postgres nodes must be configured in Master/Standby mode. You cannot install Monetization on Edge if you have multiple Postgres master nodes. For more, see [Set up Master-Standby Replication for
  Postgres](https://docs.apigee.com/private-cloud/v4.51.00/set-master-standby-replication-postgres).
- Monetization is not available with the All-In-One (AIO) configuration.

## Installation overview

The following steps illustrate how to add Monetization Services on an existing Apigee Edge
installation:

- Use the `apigee-setup` utility to update the Apigee Management Server node to enable the Monetization Services, for example, catalog management, limits and notifications configuration, billing and reporting.

  If you have multiple Management Server nodes, such as a 13-node installation, then you must
  install both Edge Management Server nodes before installing Monetization.
- Use the `apigee-setup` utility to update the Apigee Message Processor to enable the runtime components of the Monetization Services, for example, transaction recording policy and limit enforcement. If you have multiple Message Processors, install Monetization on all of them.
- Perform the Monetization onboarding process for your Edge organizations.
- Configure the Apigee Developer Services portal (or simply, *the portal* ) to support monetization. For more information, see [Configure Monetization in the Developer Portal](https://docs.apigee.com/api-platform/monetization/configure-monetization-developer-portal).

## Creating a silent configuration file for Monetization

Shown below is an example silent configuration file for a Monetization installation. Edit this
file as necessary for your configuration. Use the -f option to setup.sh to include this file.

> [!NOTE]
> **Note** : Typically, you add these properties to the same configuration file that you used to install Edge, as shown in [Install Edge components on a node](https://docs.apigee.com/private-cloud/v4.51.00/install-edge-components-node).

```
# Edge configuration properties
# Specify IP address or DNS name of node.
IP1=192.168.1.1  # Management Server, OpenLDAP, UI, ZooKeeper, Cassandra
IP2=192.168.1.2  # ZooKeeper, Cassandra
IP3=192.168.1.3  # ZooKeeper, Cassandra
IP4=192.168.1.4  # Router, Message Processor
IP5=192.168.1.5  # Router, Message Processor
IP6=192.168.1.6  # Qpid
IP7=192.168.1.7  # Qpid
IP8=192.168.1.8  # Postgres
IP9=192.168.1.9  # Postgres

# Must resolve to IP address or DNS name of host - not to 127.0.0.1 or localhost.
HOSTIP=$(hostname -i)

# Edge sys admin credentials
ADMIN_EMAIL=your@email.com
APIGEE_ADMINPW=yourPassword    # If omitted, you are prompted for it.

# Specify the Management Server port.
APIGEE_PORT_HTTP_MS=8080

#
# Monetization configuration properties.
#
# Postgres credentials from Edge installation.
PG_USER=apigee    # Default from Edge installation
PG_PWD=postgres    # Default from Edge installation

# Specify Postgres server.
MO_PG_HOST="$IP8"    # Only specify one Postgres node.

# Create a Postgres user for Monetization.
# Default username is "postgre".
# If you specify a different user, that user must already exist.
MO_PG_USER=postgre
MO_PG_PASSWD=moUserPWord

# Specify one ZooKeeper host.
# Ensure this is a ZooKeeper leader node in a multi-datacenter environment.
ZK_HOSTS="$IP2"

# Specify Cassandra information.
# Ensure CASS_HOSTS is set to the same value as when you installed Edge.
# Must use IP addresses for CASS_HOSTS, not DNS names.
CASS_HOSTS="$IP1:1,1 $IP2:1,1 $IP3:1,1"

# Default is "Apigee", unless it was changed during Edge install.
CASS_CLUSTERNAME=Apigee

# Cassandra uname/pword required only if you enabled Cassandra authentication.
# If your password uses special characters, wrap it in single quotes.
# CASS_USERNAME=
# CASS_PASSWORD=

# Specify the region.
# Default is dc-1 unless you are in a multi-datacenter environment.
REGION=dc-1

# If your Edge config file did not specify SMTP information, add it.
# Monetization requires an SMTP server.
SMTPHOST=smtp.gmail.com
SMTPPORT=465
SMTPUSER=your@email.com
SMTPPASSWORD=yourEmailPassword
SMTPSSL=y
SMTPMAILFROM="My Company <myco@company.com>"
```

**Notes**:

- If your Edge config file did not specify SMTP information, add it. Monetization requires an SMTP server.
- In a single data center installation, odd numbers of ZooKeeper nodes should be configured as `voters`. If a number of ZooKeeper nodes are even, then some nodes will be configured as `observers`. When you are installing Edge across an even number of data centers, some ZooKeeper nodes must be configured as `observers` to make the number of voter nodes odd. During ZooKeeper leader election one voter node will be elected as a `leader`. Ensure that the `ZK_HOSTS` property above specifies a leader node in a multiple data center installation.
- If you enable Cassandra authentication, you can pass the Cassandra user name and password by using the following properties:

  ```
  CASS_USERNAME
  CASS_PASSWORD
  ```

## Integrate Monetization Services with all Management Servers

Use the following procedure to integrate monetization on Management Server nodes.

1. If you are installing Monetization on an Edge topology that uses multiple Management Server nodes, such as a 13-node installation, then ensure that you installed both Management Server nodes before installing Monetization.
2. On the Management Server node, run the setup script:  

   ```
   /opt/apigee/apigee-setup/bin/setup.sh -p mo -f configFile
   ```

   The `-p mo` option specifies to integrate Monetization.

   The configuration file must be accessible or readable by the "apigee" user.
3. If you are installing Monetization on multiple Management Server nodes, repeat step 2 on the second Management Server node.

On successful configuration, an RDBMS schema for Monetization Services is created in the
PostgreSQL database. This completes the integration of Monetization Services and its associated
components with Postgres Server.

## Integrate Monetization Services with all Message Processors

Use the following procedure to integrate monetization on all Message Processor
nodes.

1. On the first Message Processor node, at the command prompt, run the setup script:

   ```
   /opt/apigee/apigee-setup/bin/setup.sh -p mo -f configFile
   ```

   The `-p mo` option specifies to integrate Monetization.

   The configuration file must be accessible or readable by the "apigee" user.
2. Repeat this procedure on all Message Processor nodes.

On successful configuration, the Message Processor is updated with Monetization Services. This
completes the integration of Monetization Services and its associated components with the Message
Processors.

## Monetization onboarding

**To create a new organization and enable monetization:**

1. Create the organization as you would any new organization. For more information, see [Onboard an organization](https://docs.apigee.com/private-cloud/v4.51.00/onboard-organization).
2. Use the monetization provisioning API as described in [Enable
   monetization for an organization](https://docs.apigee.com/api-platform/monetization/enabling-monetization-organization#apigeeedgeprivatecloud). To do this, you must have system administrator privileges.

When you next log in to the Edge UI, you see the Monetization entry in the top-level menu for
the organization:

![](https://docs.apigee.com/static/private-cloud/images/mon_ui.png)

To configure the portal to support monetization, see [Configure Monetization in
the developer portal](https://docs.apigee.com/api-platform/monetization/configure-monetization-developer-portal).

## Adding a Management Server node to a Monetization installation

If you add a Management Server to an existing Edge installation, you must ensure that you add
Monetization services to the new Management Server and configure all Management Servers so they
can communicate.

To add a Management Server:

1. Install the *new* Management Server.
2. Install Monetization on the *new* Management Server.
3. On the *original* Management Server, call the following:

   ```
   /opt/apigee/apigee-service/bin/apigee-service edge-mint-management-server mint-configure-mgmt-cluster
   ```
4. Restart the *original* Management Server:

   ```
   /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart
   ```
5. On the *new* Management Server, call the following:

   ```
   /opt/apigee/apigee-service/bin/apigee-service edge-mint-management-server mint-configure-mgmt-cluster
   ```
6. Restart the *new* Management Server:

   ```
   /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart
   ```

## Additional configuration

### Provide billing documents as PDF files

Monetization displays billing documents to end users in HTML format. To provide billing
documents as PDF files, you can integrate Monetization with a billing system that provides PDF
generation or license a supported third-party PDF library.

### Configure organization settings

To add/update organization attributes, you can use a `PUT` request, as the following
example shows:

```
curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD \
  -v http://ms_IP:8080/v1/organizations/orgId -d 'org object with attributes' -X PUT
```

Monetization responds with the organization's settings. For example:

```
{
  ...
  "displayName": "Orgnization name",
  "name": "org4",
  "properties": {
    "property": [
      ...
      {
        "name": "MINT_CURRENCY",
        "value": "USD"
      },
      {
        "name": "MINT_COUNTRY",
        "value": "US"
      },
      {
        "name": "MINT_TIMEZONE",
        "value": "GMT"
      }
    ]
  }
}
```

The following table lists the organization-level attributes that are available to configure a
mint organization.

| Attributes | Description |
|---|---|
| `MINT_TAX_MODEL` | Accepted values are "DISCLOSED", "UNDISCLOSED", "HYBRID" (default is null) |
| `MINT_CURRENCY` | ISO currency code (default is null) |
| `MINT_TAX_NEXUS` | Tax nexus (default is null) |
| `MINT_DEFAULT_PROD_TAX_CATEGORY` | Default product tax category (default is null) |
| `MINT_IS_GROUP_ORG` | IS group organization (default is "false") |
| `MINT_HAS_BROKER` | Has broken (default is false) |
| `MINT_TIMEZONE` | Timezone (default is null) |
| `MINT_TAX_ENGINE_EXTERNAL_ID` | Tax engine ID (default is null) |
| `MINT_COUNTRY` | Organization's country (default is null) |
| `MINT_REG_NO` | Organization's registration number, United Kingdom gives different number than tax ID (default is null) |
| `MINT_BILLING_CYCLE_TYPE` | "PRORATED", "CALENDAR_MONTH" (default is "CALENDAR_MONTH") |
| `MINT_SUPPORTED_BILLING_TYPE` | "PREPAID"/"POSTPAID"/"BOTH" (default is "PREPAID") |
| `MINT_IS_SEPARATE_INV_FOR_FEES` | Indicates whether a separate fee invoice should be generated (default is "false") |
| `MINT_ISSUE_NETTING_STMT` | Indicates whether netting statement should be issued (default is "false") |
| `MINT_NETTING_STMT_PER_CURRENCY` | Indicates whether netting statement should be generated per currency (default is "false") |
| `MINT_HAS_SELF_BILLING` | Indicates whether the organization has self billing (default is "false") |
| `MINT_SELF_BILLING_FOR_ALL_DEV` | Indicates whether the organization has self billing for all developers (default is "false") |
| `MINT_HAS_SEPARATE_INV_FOR_PROD` | Indicates whether the organization has separate invoice per product (default is "false") |
| `MINT_HAS_BILLING_ADJUSTMENT` | Indicates whether the organization supports billing adjustments (default is "false") |
| `features.isMonetizationEnabled` | Used by the management UI to display monetization specific menu (default is "false") |
| `ui.config.isOperator` | Used by management UI to display provider as Operator verses Organization (default is "true") |

For configuring business organization settings using the management UI, see
[Access monetization in Edge](https://docs.apigee.com/api-platform/monetization/get-started-using-monetization).

## Monetization limits

To enforce monetization limits, attach the Monetization Limits Check policy to API proxies.
Specifically, the policy is triggered under the following conditions:

- Developer accessing monetized API is not registered or has not subscribed to the rate plan.
- Developer has exceeded the transaction volume for the subscribed rate plan.
- Developer pre-paid account balance or post-paid credit limit has been reached.

The Monetization Limits Check policy raises faults and blocks API calls in situations like
those listed above. The policy extends the Raise Fault policy, and you can customize the message
returned. The applicable conditions are derived from business variables.

For more information, see [Enforce
monetization limits on API proxies](https://docs.apigee.com/api-platform/monetization/enforce-monetization-limits-using-monetization-limits-check-policy).