Chapter 24. Credit card gateways for payments

As a 3scale API provider, you can define the payment gateways for credit cards in order to monetize subscriptions to your APIs.

24.1. Credit card gateways supported by 3scale

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

  • Braintree
  • Stripe

Online payment services must display a mandate when collecting credit card data. A mandate is a record of the permission a customer has given you to debit their payment method. The mandate should state clearly that the supplied payment method will be used to collect subsequent payments for services. For more information regarding mandates for Stripe and Braintree, see the external documentation links for the respective payment gateways listed under Additional resources.

Additional resources

24.2. Configuring Stripe as a credit card gateway

As a 3scale API provider, configure the Admin Portal and the Developer Portal with Stripe as a payment gateway to receive payments from subscriptions to your APIs by using Stripe as a credit card gateway.


  • You must have an account with Stripe.
  • You must have Stripe administrator permissions.


To configure 3scale with Stripe as a payment gateway, follow these steps:

Generating an access token with the Billing API scope in the 3scale Admin Portal

  1. In the 3scale Admin Portal, go to Account Settings > Personal > Tokens.
  2. Create a Read & Write token with the Billing API scope:

    1. Click Add Access Token.
    2. Specify a name for the token.
    3. Choose the scope: Billing API.
    4. Select the permission level: Read & Write.
    5. Click Create Access token.
    6. Copy the access token.

      • Ensure you copy the access token to a file text. The access token will not be displayed afterwards.
    7. To finish the token generation, click I have copied the token.

Back to Procedure.

Obtaining the keys and the webhook secret from Stripe

In your Stripe account, get the Secret Key, and the Publishable Key:

  1. Open the Stripe dashboard.
  2. Find your API keys by following the instructions in the Stripe documentation.
  3. Copy the Secret Key, and the Publishable Key

Still in your Stripe account, create a Webhook Signing Secret:

  1. Go to Developers > Webhooks.
  2. Click Add endpoint
  3. Fill in with the following endpoint URL:

  4. In Events to send, add payment_intent.succeeded.
  5. Click Add endpoint.
  6. Click to reveal the signing secret of the webhook you just created and take note of this secret. This is the Webhook Signing Secret.

Back to Procedure.

Configuring charging in the 3scale Admin Portal

In the 3scale Admin Portal:

  1. Go to Audience > Billing > Charging & Gateway.
  2. Select Charging enabled and click Save.
  3. In Credit card gateway > Gateway, select Stripe as the gateway.
  4. Add the Secret Key, the Publishable Key and the Webhook Signing Secret you obtained from your Stripe account in Obtaining the keys and the webhook secret from Stripe.
  5. Click Save.

Back to Procedure.

Editing credit card details in the 3scale Developer Portal

  1. Login to the 3scale Developer Portal with a developer account.
  2. Go to Settings > Credit Card Details.
  3. Add the following credit card details: credit card number, expiration date and CVC.
  4. Click Save details.

Back to Procedure.

Updating the text of unsuccessfully charged email response

In connection with the fixes for SCA payments, the text of the invoice_messenger_unsuccessfully_charged_for_buyer.text.liquid email requires a manual update in 3scale 2.10.

  1. In the 3scale Admin Portal, go to Audience > Messages > Email Templates.
  2. Select Invoice charge failure for buyer with retry.
  3. Click Override.
  4. Update the template message: This is the complete text to be used in the unsuccessfully charged email response:

    Dear {{ }},
    Thank you for using our service.
    We're sorry to inform you that your last payment was declined.
    This may have been caused by a few common reasons:
    - A new authentication policy enforced by your bank
    - An expired credit card
    - Insufficient funds on the account
    To continue using your service, verify the status of your credit card and update or re-enter the credit card details at {{payment_url}}.
    If you need help, don't hesitate to contact us at {{ provider.finance_support_email }}.
    Best regards,
    The {{ }} API Team
  5. Click Create Email Template.

With these steps, you have updated the email template for the unsuccessfully charged email response.

Back to Procedure.

Optional: Allowing payments of rejected invoices via the Developer Portal

If you want to allow the payment of rejected invoices via the Developer Portal, you can update the invoices template in the Admin Portal. Note that this procedure is intended for existing instances of the Developer Portal:

  1. In the 3scale Admin Portal, go to Audience > Developer Portal > Content.
  2. Edit Root > Invoices > Show template.
  3. Replace these lines of code:

    <a href="{{ urls.invoices }}">
      <i class="fa fa-chevron-left"></i>
        {{ invoice.period_begin | date: '%B, %Y' }} Invoice

    With this snippet:

    <div class="clearfix">
      <a href="{{ urls.invoices }}">
        <i class="fa fa-chevron-left"></i>
        {{ invoice.period_begin | date: '%B, %Y' }} Invoice
        {% if invoice.pay_now? %}
          <a href="{{invoice.url}}/payment" class="pull-right btn btn-success pay-invoice-btn">Pay invoice</a>
        {% endif %}

Back to Procedure.

Additional resources

24.3. Braintree integration

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

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

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


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.


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

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