Chapter 3. Credit Card Flow

This guide will help you define a great workflow in your Developer Portal to ensure that developers submit their credit card details before they gain access to your paid API(s).

It’s increasingly common to see businesses charge for access to their APIs. Sometimes the entire business model of a company is built around paid APIs, while other times it’s an important revenue stream to cover costs or generate profits for the company.

3.1. Prerequisites

  • 3scale finance module (billing and charging) activated and configured
  • Paid plans defined (usually application plans)

After following the steps detailed below, all the existing developers who have paid plans but no credit card details entered, will be redirected to the credit card details form. They will not be allowed to access the portal until they have successfully entered their credit card details.

3.2. Step 1: Hide certain menu items when credit card details are missing

When a developer signs up to a paid plan and is required to fill in the credit card details, it is recommended to hide some menu items since it will not be possible to navigate there until the credit card is entered. In order to do so, you will need to change the following 2 menu partials:

  • users_menu
  • submenu

3.2.1. Editing users_menu partial

You will need to replace the whole of the partial content with the below:

<ul class="nav nav-tabs">
   {% unless current_account.requires_credit_card_now? %}
     <li class="{% if urls.account_overview.active? %}active{% endif %}">
       <a href="{{ urls.account_overview }}">Account Details</a>
     </li>

     {% if provider.account_management_enabled? %}
       {% include 'menu_item' with urls.users %}

       {% if provider.multiple_users_allowed? %}
         {% include 'menu_item' with urls.invitations %}
       {% endif %}
     {% endif %}

     {% if provider.account_plans.size > 1 %}
       {% include 'menu_item' with urls.account_plans %}
     {% endif %}
   {%  endunless %}

   {% if provider.finance_allowed? %}
     {% unless current_account.requires_credit_card_now? %}
       {% include 'menu_item' with urls.invoices %}
     {% endunless %}

     {% if urls.payment_details %}
       {% include 'menu_item' with urls.payment_details %}
     {% endif %}
   {% endif %}
 </ul>

If you have customised this partial already, e.g by adding some css, modifying the HTML tags, etc…​ you should use the new liquid tag for this purpose accordingly:

current_account.requires_credit_card_now?

3.2.2. Editing submenu partial

The developer gains access to their keys to start making calls on your API through the API credentials. The changes below ensure that you only display the links if the account does not require credit card details to be entered e.g because there are no paid plans or if the credit card is already available. If you wanted to be completely strict about this, you would edit the system page for displaying the keys to restrict the display – but this would be an advanced customization. You may also want to delete the snippet to display credentials directly on the home page after login.

You will need to replace the whole of the partial content with the below:

    {% if current_user %}
      {% unless current_account.requires_credit_card_now? %}
        <ul class="nav navbar-nav">

          {% if provider.multiple_applications_allowed? %}
            <li class="{% if urls.applications.active? %}active{% endif %}">
              <a href="{{ urls.applications }}">{{ urls.applications.title }}</a>
            </li>
            {% elsif current_account.applications.first == present%}
            {% assign app = current_account.applications.first %}
            <li class="{% if app.url.active? %}active{% endif %}">
              <a href="{{ app.url }}">API Credentials</a>
            </li>
            {% elsif current_user.can.create_application? %}
            <li class="{% if url.new_application.active? %}active{% endif %}">
              <a href="{{ urls.new_application }}">Get API Credentials</a>
            </li>
          {% else %}
            <!-- You don't have any application neither can create one. Bad luck. -->
          {% endif %}

          {% assign live_apps_present = current_account.applications | map: 'state' | any: 'live' %}
          {% if live_apps_present %}
            <li class="{% if urls.stats.active? %}active{% endif %}">
              <a href="{{ urls.stats }}">Statistics</a>
            </li>
          {% endif %}

          {% if provider.multiple_services_allowed? %}
            <li class="{% if urls.services.active? %}active{% endif %}">
              <a href="{{ urls.services }}">{{ urls.services.title }}</a>
            </li>
          {% endif %}

          <li><a class="{% if urls.docs.active? %}active{% endif %}" href="/docs">Documentation</a></li>

        </ul>
      {% endunless %}
      <ul id="user_widget" class="nav navbar-nav navbar-right">
        {% unless current_account.requires_credit_card_now? %}
          <li class="{% if urls.messages_inbox.active? %}active{% endif %}">
            <a href="{{ urls.messages_inbox }}">
              Messages
              {% if current_account.unread_messages.size > 0 %}
                {{ current_account.unread_messages.size }}
              {% endif %}
            </a>
          </li>
          <li class="{% if urls.account_overview.active? %}active{% endif %}">
            <a href="{{ urls.account_overview }}">

              Settings
            </a>
          </li>
        {% endunless %}
        <li>
          <a id="sign-out-button" class="pull-right sign-out" title="Logout {{ current_user.username }}" href="{{ urls.logout }}">

          </a>
        </li>
      </ul>

    {% else %}
      <ul class="nav navbar-nav">
        <li><a href="/docs">Documentation</a></li>
        <li><a href="/#plans">Plans</a></li>
      </ul>
      <ul class="nav navbar-nav navbar-right">
        <li>
          <a href="{{ urls.login }}">
            Sign in
          </a>
        </li>
      </ul>
    {% endif %}

Again, if you have customised this partial already, you will need to modify your version accordingly using the same new liquid tag: current_account.requires_credit_card_now?

3.3. Step 2: Enable Feature

To enable this feature, you must enable the following 2 switches:

Switches can be found in Audience > Developer Portal > Feature Visibility.

  • Finance
  • Credit Card on Signup (only available if you are on an older 3scale account.)

3.4. Step 4: Ensure credit card is entered by developer when upgrading from a free to a paid plan

You may allow developers to select plans when changing plans. The ideal setting is Request credit card entry for paid plans. This will ensure that if a paid plan is selected, the plan change can only be done instantly if a credit card is stored. Otherwise a notification is displayed to point the developer to the location to enter their card details.

This setting is defined from the Admin Portal. Go to [your_API_name] > Integration > Settings > Application Plans. Here you can select the option Request credit card entry for paid plans in the section Application Plans of the settings form.

To enable this behavior, you will need to make changes to the following CMS pages:

  • applications/show template
  • applications/form partial

3.4.1. Editing applications/show Template

You will need to look for plan_widget in the page code and change it to the following:

{% plan_widget application, wizard: true %}

If you have added the plan_widget in any other pages, you will need to update those to match the above snippet.

3.4.2. Editing applications/form partial

Follow the same instructions above to change any instances of plan_widget in the applications/form partial to conform to the new snippet.

And that’s it! You can now enforce the addition of credit card details before allowing usage of your API for paid plans.