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
- Stripe: Accept a SEPA Direct Debit payment
- Braintree: Recurring Transactions
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 an account with Stripe.
- You must have Stripe administrator permissions.
Procedure
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.
- Obtaining the keys and the webhook secret from Stripe.
- Configuring charging in the 3scale Admin Portal.
- Editing credit card details in the 3scale Developer Portal
-
Updating the text of
unsuccessfully charged
email response - Optional: Allowing payments of rejected invoices via the Developer Portal
Generating an access token with the Billing API scope in the 3scale Admin Portal
- In the 3scale Admin Portal, go to Account Settings > Personal > Tokens.
Create a Read & Write token with the Billing API scope:
- Click Add Access Token.
- Specify a name for the token.
- Choose the scope: Billing API.
- Select the permission level: Read & Write.
- Click Create Access token.
Copy the access token.
- Ensure you copy the access token to a file text. The access token will not be displayed afterwards.
- To finish the token generation, click I have copied the token.
Obtaining the keys and the webhook secret from Stripe
In your Stripe account, get the Secret Key, and the Publishable Key:
- Open the Stripe dashboard.
- Find your API keys by following the instructions in the Stripe documentation.
- Copy the Secret Key, and the Publishable Key
Still in your Stripe account, create a Webhook Signing Secret:
- Go to Developers > Webhooks.
- Click Add endpoint
Fill in with the following endpoint URL:
https://<Your-provider-admin-domain>/api/payment_callbacks/stripe_callbacks?access_token=<value-of-access-token>
-
In Events to send, add
payment_intent.succeeded
. - Click Add endpoint.
- Click to reveal the signing secret of the webhook you just created and take note of this secret. This is the Webhook Signing Secret.
Configuring charging in the 3scale Admin Portal
In the 3scale Admin Portal:
- Go to Audience > Billing > Charging & Gateway.
- Select Charging enabled and click Save.
- In Credit card gateway > Gateway, select Stripe as the gateway.
- 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.
- Click Save.
Editing credit card details in the 3scale Developer Portal
- Login to the 3scale Developer Portal with a developer account.
- Go to Settings > Credit Card Details.
- Add the following credit card details: credit card number, expiration date and CVC.
- Click Save details.
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.
- In the 3scale Admin Portal, go to Audience > Messages > Email Templates.
- Select Invoice charge failure for buyer with retry.
- Click Override.
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
- Click Create Email Template.
With these steps, you have updated the email template for the unsuccessfully charged
email response.
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:
- In the 3scale Admin Portal, go to Audience > Developer Portal > Content.
- Edit Root > Invoices > Show template.
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>
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:
The API keys page still hides the private key, so select the option to view it:
Finally you have the Public Key, Private Key, and Merchant ID that you’ll need for the 3scale billing settings:
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.
You should see a drop-down called Gateway near the bottom of the page. Change it to Braintree (Blue Platform).
The form below the drop-down should change to show two fields. Insert your Braintree keys and click Save.
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 customer.id
which is composed of 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID]
24.3.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.