GoCardless API Essential Guide

What type of API does GoCardless provide?

GoCardless provides a REST API for developers to integrate with their platform. The key features of the GoCardless REST API include:

• Allowing developers to create powerful integrations with GoCardless.
• Enabling developers to integrate as a Merchant to take payments on their own behalf, or as a Partner to create and manage multiple merchants.
• Providing webhooks to notify Merchants of any changes in the status of resources, such as determining when a bill has been paid.

GoCardless offers detailed documentation for their API and provides technical support for developers via email at [email protected]. The API supports features like recurring payments, invoice payments, and international payments.

Does the GoCardless API have webhooks?

Yes, the official GoCardless API does have webhooks. Here are the key points about GoCardless webhooks:

Webhook Availability

GoCardless provides webhooks as a way to receive real-time notifications about events happening in your account. This allows you to take automated actions in response to these events.

Types of Events

You can subscribe to various types of events through GoCardless webhooks. Some examples include:

• When a payment fails due to lack of funds
• When a customer cancels their mandate with the bank
• When a customer's subscription generates a new payment

Webhook Implementation

Here are some important details about implementing GoCardless webhooks:

1. GoCardless sends a request to your server to alert you of an event.

2. You can specify a webhook URL in your GoCardless account where these notifications will be sent.

3. Webhooks contain detailed information about the event, including the event type, resource type, and any associated metadata.

Event Metadata

You can include metadata when triggering certain actions via the API, which will then be sent in the associated webhook. For example:

{
    "events":[
    {
        "id":"EV000PKARAE83C",
        "created_at": "2017-06-14:10:32:47.123Z",
        "resource_type": "payments",
        "actions": "resubmission_requested",
        "links": {
            "payment": "PM0004RZ68FD1A"
        },
        "details": {
            "origin": "api",
            "cause": "payment_retried",
            "description": "As attempt to retry this payment was requested"
        },
        "metadata"{
            "reason": "Customer request"
        }
    }
    ]
}

This example shows a webhook event for a payment retry, including custom metadata.

Webhook Reliability

GoCardless has a retry mechanism for failed webhook deliveries:

• If a webhook fails to be delivered, GoCardless will retry up to 8 times at increasing intervals.
• Failures can occur due to timeouts, unauthorized access, or redirects.

By using GoCardless webhooks, you can create a more responsive and automated integration with their payment processing system.

Rate Limits and other limitations

Based on the search results provided, here are the key points regarding the API Rate Limits of the GoCardless API:

Current Rate Limits

• Starting from August 19, 2024, GoCardless implemented a limit of 10 API requests per day for each access scope (details, balances, transactions) on account id level.

• In the next phase, GoCardless plans to establish a limit of four requests per day for each access scope.

Implementation Details

• The rate limits are applied per bank account.

• Each endpoint (details, balances, transactions) has its own rate limit.

• If you exceed the rate limit, you will receive an error.

Impact on Users

• This limitation can significantly affect users with multiple accounts to monitor, as they may only be able to fetch data for 1 to 4 accounts per day, depending on how many API calls Firefly III makes for each account.

Possible Exemptions

• GoCardless mentions that if your use case may qualify for an exemption, such as if end users are actively requesting account information more than four times a day, you can reach out to their sales or support team for assistance.

Additional Rate Limit Information

• For bulk operations or making many requests in a short period, GoCardless has a separate rate limit of up to 1000 requests per minute.

Best Practices

1. Monitor your API usage carefully to avoid hitting the rate limits.
2. Implement proper error handling for rate limit errors (429 Too Many Requests).
3. Consider reaching out to GoCardless for exemptions if your use case requires more frequent updates.
4. Optimize your API calls to make the most efficient use of the available requests.

It's important to note that these rate limits are subject to change, and it's advisable to keep an eye on any updates from GoCardless regarding their API usage policies.

Latest API Version

Unfortunately, I couldn't find specific information about the most recent version of the GoCardless API in the provided search results. The search results contain general information about GoCardless and its API capabilities, but do not mention a specific version number.

Here are some key points to consider:

1. GoCardless provides a RESTful API for integrating payment functionality into applications.

2. The API allows developers to collect bank debit payments across 30+ countries from a single integration.

3. GoCardless offers client libraries for PHP, Java, Ruby, Python, and .NET to make integration easier.

4. They provide a free sandbox environment for end-to-end testing.

5. The API documentation includes full reference documentation and step-by-step guides.

To find the most recent version of the GoCardless API, I would recommend:

1. Checking the official GoCardless API documentation directly on their website.
2. Looking for any changelog or release notes in the documentation.
3. Contacting GoCardless support if the version information is not clearly stated in the documentation.

It's important to always use the most recent version of an API to ensure you have access to the latest features and security updates. When integrating with the GoCardless API, make sure to review their documentation thoroughly and stay informed about any updates or changes to the API.

How to get a GoCardless developer account and API Keys?

To get a developer account for GoCardless and create an API integration, you need to follow these steps:

1. Sign up for a sandbox account

   • Go to the GoCardless website and create a sandbox account
   • If you already have a sandbox account, log in to your dashboard

2. Create an OAuth app

   • Navigate to the Developer section of your dashboard
   • Create a new OAuth app
   • You'll receive a client_id and client_secret which you'll use to identify your integration

3. Get an access token

   • Create a read-write access token through the Developer section of your sandbox dashboard
   • You'll use this token when sending requests to the GoCardless API

4. Familiarize yourself with the documentation

   • Review the developer documentation, including the getting started guide and full API reference
   • Look at code examples provided for various programming languages

5. Start implementing the API

   • Use one of the official client libraries provided for languages like Java, JavaScript, Python, Ruby, PHP, and .NET
   • Implement key flows like creating customers, mandates, and payments

6. Test thoroughly

   • Create test customers and payments in the sandbox
   • Implement webhook handling to receive real-time updates

7. Go live

   • Sign up for a live GoCardless account
   • Create OAuth credentials and access tokens for the live environment
   • Update your integration to use the live API endpoints and credentials

What can you do with the GoCardless API?

Based on the search results provided, here is a list of data models you can interact with using the GoCardless API, along with what is possible for each:

Payments

• Process one-off payments, subscriptions, invoices, and installments
• Utilize bank debit for payment processing
• Handle international payments from 30+ countries

Bank Account Data

• Access account information, balances, and transaction history
• Connect to 2,300+ banks across the UK and Europe
• Choose which banks to allow connections from
• Select specific data to access for powering user experiences

Customer Information

• Collect and store customer billing information
• Gather first and last names of account holders (required by GoCardless)
• Collect address details for specific payment methods

Mandates

• Create and manage direct debit mandates
• Utilize Verified Mandates for payer authentication

Transactions

• Process charges and refunds
• Handle automated retries for SEPA payments
• Manage transaction limits based on payment methods

Webhooks

• Set up and receive notifications for late failures and chargebacks

Currencies

• Support multiple currencies including EUR (SEPA), USD (ACH), GBP (BACS), and AUD (BECS)

Bank Connections

• Manage bank connections (up to 50 on the free plan)
• Continuously sync new data from connected banks

Open Banking

• Process open banking payments directly from customers' bank accounts

Fraud Protection

• Utilize Protect+ for advanced fraud protection on recurring payments

It's important to note that the specific capabilities and limitations may vary depending on the API version used (V2 or V3) and the integration method (API, Recurly.js, etc.). Additionally, some features may require specific permissions or additional setup with GoCardless.