Chapter 24. Credit card gateways for payments

As a 3scale API provider, define the payment gateways for credit cards 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.

Prerequisites

  • You must have a Stripe account.

    • Stripe recommends you use separate Stripe sub-accounts for each business or project.
    • See the Stripe documentation for Multiple Accounts.
  • You must have Stripe administrator permissions.

Procedure

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

  1. Generating an access token with the Billing API scope in the 3scale Admin Portal.
  2. Obtaining the keys and the webhook secret from Stripe.
  3. Configuring charging in the 3scale Admin Portal.
  4. Editing credit card details in the 3scale Developer Portal
  5. Updating the text of unsuccessfully charged email response.

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

24.2.2. Obtaining the keys and the webhook secret from Stripe

Note
  • Configuring the webhook in Stripe is required.
  • Use the webhook to notify 3scale that the payment has succeeded.
  • 3scale then updates the state of the invoice and prevents further attempts to charge.

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: 

    https://<Your-provider-admin-domain>/api/payment_callbacks/stripe_callbacks?access_token=<value-of-access-token>
  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.

24.2.3. 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 Section 24.2.2, “Obtaining the keys and the webhook secret from Stripe”.
  5. Click Save.

Back to Procedure.

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

24.2.5. 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 {{ account.name }},

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 {{ provider.name }} 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.

Additional resources

24.3. Configuring Braintree as a credit card gateway

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

Prerequisites

  • You must have an account with Braintree.

  • If you want to ensure a secure checkout for your customers with 3D Secure (3DS), you must have 3DS enabled in your Braintree account before you enable 3DS for 3scale.

    • By default, both 3scale and Braintree have 3DS as off(disabled).

Procedure

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

  1. Obtaining the keys and the merchant identifier from Braintree.
  2. Configuring charging in the 3scale Admin Portal.
  3. Editing credit card details in the 3scale Developer Portal

Obtaining the keys and the merchant identifier from Braintree

From your Braintree account, get the Public Key, the Merchant ID, and the Private Key. For more information about obtaining these values, refer to the Braintree documentation listed under Additional resources.

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.

  3. Select the currency.

    • The currency type specified on the 3scale Billing page must match the currency type used in your Braintree merchant account.
  4. Click Save.
  5. Under Credit card gateway > Gateway, select Braintree as the gateway.
  6. Add the Public Key, the Merchant ID and the Private Key you obtained from your Braintree account in Obtaining the keys and the merchant identifier from Braintree.
  7. To enable 3DS, select 3D Secure Enabled.
  8. Click Save changes.

Back to Procedure.

Editing credit card details in the 3scale Developer Portal

As a 3scale API consumer, add or edit the credit card details in the 3scale Developer Portal. To match the financial details with the entity that has issued your credit card, all the fields listed in this window are mandatory.

  1. Login to the 3scale Developer Portal with a developer account.
  2. Go to Settings > Credit Card Details.
  3. Click the Add Credit Card Details and Billing Address link.
  4. Add the payment details: first name, last name, phone.
  5. Add the credit card details: credit card number, expiration date and CVC.
  6. Add the billing address details: company, street address, zip/postal code, city and state/region. Then, select the country.
  7. Click Save details.
  8. If you are prompted, complete two-factor authentication (2FA) for your purchase. For example, if your bank has enabled the SMS 2FA option, you will have to complete the authentication process using this method.

Back to Procedure.

Additional resources

24.4. Allowing payments of rejected invoices via the Developer Portal

As a 3scale API provider, allow the payment of rejected invoices via the Developer Portal. To enable these payments, update the Invoices template in the Admin Portal. Note that this procedure is intended for existing instances of the Developer Portal.

Prerequisites

  • You must have administrator permissions for 3scale.
  • You must have an account with Stripe or Braintree.

Procedure

To allow payments of rejected invoices via the Developer Portal, follow these steps:

  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>
    Cancel
    </a>
    {{ invoice.period_begin | date: '%B, %Y' }} Invoice

    With this snippet: 

    <div class="clearfix">
  <a href="{{ urls.invoices }}">
    <i class="fa fa-chevron-left"></i>
      Cancel
    </a>
    {{ 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 %}
</div>

24.5. Troubleshooting issues with credit card gateways

As a 3scale API provider working with either Stripe or Braintree as payment gateways, you can troubleshoot some issues with these credit card gateways.

Stripe

  • 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]

Braintree

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

  • For credit cards that are stored in the 3scale Developer Portal without 3D Secure (3Ds) enabled, these are the suggested solutions to integrate 3scale with Braintree:

    1. 3scale API providers: follow the steps listed in Configuring charging in the 3scale Admin Portal.
    2. 3scale API consumers: follow the steps listed in Editing credit card details in the 3scale Developer Portal.
  • 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]