Chapter 23. Configuring Billing Settings

This document describes how the Billing feature works in Red Hat 3scale API Management.

Billing settings are divided into Charging & Gateway and Credit Card Policies, both can be found in Audience > Billing in the Admin Portal.

23.1. Billing modes (Charging & Gateway)

Billing in 3scale is based on the calendar month, and can be Prepaid and Postpaid.

  • In the Prepaid mode, all fixed fees and setup fees are billed at the beginning of the month or at the beginning of any prorated billing period. Variable costs are always calculated and billed at the beginning of the following month.
  • In Postpaid mode, all fixed fees as well as variable costs are billed at the beginning of the following month.

For more details see Automated billing process.

23.2. Charging enabled (Charging & Gateway)

This setting enables credit card transactions. When this setting is on, all due invoices will be charged using the selected payment gateway. If you leave this setting off, billing will take place and invoices will be issued, but no real payment transaction will take place.

23.3. Currency (Charging & Gateway)

Select the currency in which billing and the credit card transactions will be made. Please make sure that the selected currency is supported by your payment gateway. This setting is global and applies to all invoices and transactions; it is not possible to set different currencies for different developer accounts.

23.4. Invoice footnote (Charging & Gateway)

The text introduced in the Invoice footnote field will appear at the bottom of every PDF invoice. You can use this field to provide additional information about the charging and billing policy for your customers.

If the text of the footnote is changed, it doesn’t automatically apply to the invoices, for which the PDF has already been generated. However, it is possible to apply the change by regenerating the PDF of the invoices.

23.5. Text to show if VAT/Sales Tax is 0% (Charging & Gateway)

This field is used to add a text message to the PDF invoice, in case VAT / Sales Tax is 0% for the billed account. This line will only appear if the VAT / Sales Tax is set to 0 explicitly, otherwise it will not be shown. This text will also appear on the Invoice page in the Admin Portal.

See more about this setting in VAT / Sales Tax section

23.6. YAML configuration for currencies

The currencies.yml file allows you to configure a list of currencies for your 3scale deployment. 3scale uses three-letter currency codes based on ISO 4217.

Important
  • Ensure that the payment gateway supports the selected currency.

  • 3scale integrates with the following payment gateways for credit card transactions:

    • Braintree
    • Stripe

23.6.1. Changing the currencies configuration in OpenShift

To change the currencies config, do the following:

Procedure

  1. Add the source for the new content of currencies.yml as an entry of the system config map. The following example shows you how to add and additional currency, the ARS - Argentine Peso to the default list of currencies: 

    oc patch configmap system --type merge -p "{\"data\": {\"currencies.yml\": \"production:\n  'USD - American Dollar': 'USD'\n  'EUR - Euro': 'EUR'\n  'GBP - British Pound': 'GBP'\n  'NZD - New Zealand dollar': 'NZD'\n  'CNY - Chinese Yuan Renminbi': 'CNY'\n  'CAD - Canadian Dollar': 'CAD'\n  'AUD - Australian Dollar': 'AUD'\n  'JPY - Japanese Yen': 'JPY'\n  'CHF - Swiss Franc': 'CHF'\n  'SAR - Saudi Riyal': 'SAR'\n  'ARS - Argentine peso': 'ARS'\n\"}}"
    Note

    To see an example of content for the currencies.yml config file, access the default YAML file: currencies.yml. The file shows a default configuration of a new 3scale deployment: 

    base: &default
  'USD - American Dollar': 'USD'
  'EUR - Euro': 'EUR'
  'GBP - British Pound': 'GBP'
  'NZD - New Zealand dollar': 'NZD'
  'CNY - Chinese Yuan Renminbi': 'CNY'
  'CAD - Canadian Dollar': 'CAD'
  'AUD - Australian Dollar': 'AUD'
  'JPY - Japanese Yen': 'JPY'
  'CHF - Swiss Franc': 'CHF'
  'SAR - Saudi Riyal': 'SAR'
production:
  <<: *default
preview:
  <<: *default

  2. Include the new ConfigMap entry currencies.yml in the system-config volume of system-(app|sidekiq) DeploymentConfig. This will mount the new the content inside the relevant containers and activate the new config. 

    export PATCH_SYSTEM_VOLUMES='{"spec":{"template":{"spec":{"volumes":[{"configMap":{"items":[{"key":"zync.yml","path":"zync.yml"},{"key":"rolling_updates.yml","path":"rolling_updates.yml"},{"key":"service_discovery.yml","path":"service_discovery.yml"},{"key":"currencies.yml","path":"currencies.yml"}],"name":"system"},"name":"system-config"}]}}}}'
    oc patch dc system-app -p $PATCH_SYSTEM_VOLUMES
oc patch dc system-sidekiq -p $PATCH_SYSTEM_VOLUMES
    unset PATCH_SYSTEM_VOLUMES

23.6.2. Verifying the new currencies

To verify the currencies are available in your 3scale Admin Portal, do the following:

Procedure

  1. Go to Audience > Billing > Charging & Gateway.
  2. Check that the list of currencies is available from the Currency drop-down list.
  3. Choose the currency you intend to use.

23.7. Billing periods for invoice ids (Charging & Gateway)

Invoices in 3scale have two types of identifiers:

Actual ID
which uniquely identifies the invoice in the database. This is a numeric ID, which appears in the invoice URL (i.e. https://<dashboard_domain>/buyers/accounts/<acount_id>/invoices/<invoice_id>) and is used as the invoice ID in the Billing API.
Friendly ID
which appears on the invoice, is a user-friendly identifier. It should be unique per 3scale account, although it is technically possible to have duplicated friendly identifiers. In case that 3scale recognizes duplicate identifiers, you will see a warning message similar to: This invoice id is already in use and should probably be changed. If the friendly identifier is displayed as fix for more than 24 hours, contact support.

This setting defines the format of the Friendly ID of the invoice:

monthly (default)
YYYY-MM-XXXXXXXX, i.e. the ID includes the year, the month and the number of the invoice. Example: 2018-02-00000013
yearly
YYYY-XXXXXXXX, i.e. it only includes the year and the number. Example: 2018-00000001

The only effect of changing the Billing periods for invoice identifiers from monthly to yearly is changing the friendly identifier format. This modification does not change the billing cycle period. Only monthly billing is supported by 3scale API Management. Changing the format of the invoice indetifiers to yearly can be used, if there is such a requirement from your accounting department.

If you need to charge the customers yearly, billing should be handled manually – you can create a new invoice and add a line item with the yearly cost. If you prefer to use yearly charging, you may also want to set your application plans to be free, to make sure the invoices are not generated and/or charged automatically each month.

23.8. Credit Card Policies

Here you can configure the path to the following pages:

  • Legal Terms page
  • Privacy page
  • Refund page