Chapter 14. 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.

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

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

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

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

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

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

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

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

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

14.8. Credit Card Policies

Here you can configure the path to the following pages:

  • Legal Terms page
  • Privacy page
  • Refund page

14.9. Credit Card Gateways

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

  • Braintree
  • Stripe

14.9.1. Stripe integration (recommended)

After completing these steps you will have configured Stripe as a payment gateway for your account. This will allow your developers to enter their credit card details, and you can automatically charge them through Stripe for access to your API, according to the calculated invoices.

If you enable credit card charging for your paid API, then one key step is to setup your payment gateway. There are a number of alternative payment gateways which you can use with your 3scale account. Here we cover the steps for Stripe.

14.9.1.1. Prerequisites

Before you start these steps, you will need to open an account with Stripe.

14.9.1.2. Getting your API keys from Stripe

Log in to your Stripe account, and get your API keys at https://dashboard.stripe.com/account/apikeys. You will need two keys: a "secret" one, and a "publishable" one. Use the "test" set when you’re doing tests and the "live" ones when you are ready to start charging.

Stripe Integration

14.9.1.3. Configuring settings in 3scale

You need to tell 3scale to start using these API keys. To do this, log in to your 3scale Admin Portal. and go to Audience > Billing > Charging & Gateway.

Billing page

If the Charging Enabled flag is not active, enable it and click Save.

Enable charging

You should see a drop-down called Gateway near the bottom of the page. Change it to Stripe.

Billing gateway

The form below the drop-down should change to show two fields. Insert your Stripe API keys and click Save.

Stripe billing gateway

You might see a couple of alerts when you change your payment gateway. This is expected. Read them and accept them if they appear.

The payment gateway is now set up, but your users might not be able to use it yet since the it’s not configured in the CMS. Go to Developer portal, and click on the template called Payment Gateway / Show on the left navigation pane.

Developer portal - Billing

If it’s not there already, add the following code before {% when "braintree_blue" %}:

{% when "stripe" %}
 <p><a href="{{ current_account.edit_stripe_billing_address_url }}">Edit billing address</a></p>

 {% if current_account.has_billing_address? %}
   {% stripe_form "Edit Credit Card Details" %}
 {% else %}
   <p>After entering billing address, the option to enter credit card will be enabled.</p>
 {% endif %}

Finally click Save and Publish. Your users should now be able to pay you using the Stripe gateway.

Note

In order to map your data from Stripe with your data on 3scale, you can use the Stripe field called metadata.3scale_account_reference which is composed of 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID]

14.9.2. Braintree integration

These are the steps to set up the Braintree gateway in order to to charge for use of your API.

14.9.2.1. Getting your API keys from Braintree

You’ll need to open an account with Braintree. You need a Gateway and Merchant account plus Vault. As an optional extra, you can choose to allow American Express cards as a payment method.

To begin, log in to your Braintree account. Then find your API keys in the Account > MyUser area:

Braintree Settings

The API keys page still hides the private key, so select the option to view it:

Braintree keys

Finally you have the Public Key, Private Key, and Merchant ID that you’ll need for the 3scale billing settings:

Braintree keys

14.9.2.2. Configuring settings in 3scale

You need to tell 3scale to start using these API keys. To do this, log in to your 3scale Admin Portal and go to Audience > Billing > Charging & Gateway.

Ensure that the currency type specified on the billing page matches the currency type used in your Braintree merchant account.

Billing

If the Charging Enabled flag is not active, enable it and click Save.

Billing charging enabled

You should see a drop-down called Gateway near the bottom of the page. Change it to Braintree (Blue Platform).

Billing Gateway

The form below the drop-down should change to show two fields. Insert your Braintree keys and click Save.

Ogone billing gateway

You might see a couple of alerts when you change your payment gateway. This is expected. Read and accept them if they appear.

Your users should now be able to pay you using the Braintree gateway.

Note

In order to map your data from Braintree with your data on 3scale, you can use the Braintree field called customer.id which is composed of 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID]

14.9.2.2.1. Troubleshooting

In case your account is in the sandbox mode and you encounter any problems, you will have to change it to production.