GoCardless 11.1.0

.NET Client for the GoCardless API

For full details of the GoCardless API, see the API docs.

• "Getting started" guide
• API Reference
• NuGet Package

Installation

To install GoCardless, run the following command in the Package Manager Console

Install-Package GoCardless -Version 11.1.0

Usage

Note: This README will use "customers" in examples throughout, but every endpoint in the API is available in this library.

Initialising the client

The client is initialised with an access token and an environment.

var accessToken = "your_access_token";
var gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

GET requests

Individual resources

You can retrieve individual resources by ID using that resource's GetAsync method:

var customerResponse = await gocardless.Customers.GetAsync("CU0123");
var customer = customerResponse.Customer;

Lists of resources

There are two ways to list resources. You can either make single requests for lists with ListAsync:

var customerRequest = new GoCardless.Services.CustomerListRequest()
{
    Limit = 100
};

var customerListResponse = await gocardless.Customers.ListAsync(customerRequest);

foreach (var customer in customerListResponse.Customers)
{
    Console.WriteLine(customer.GivenName);
}

Console.WriteLine("Next page cursor: " +  customerListResponse.Meta.Cursors.After);

or use the lazy pagination offered by All:

var customerRequest = new GoCardless.Services.CustomerListRequest()
{
    Limit = 100
};

var customerListResponse = gocardless.Customers.All(customerRequest);
foreach (var customer in customerListResponse)
{
    Console.WriteLine(customer.GivenName);
}

The lazy pagination approach is generally simpler - it automatically makes as many API requests as needed to return the whole list as an enumerable, and you don't need to take care of pagination manually.

POST/PUT requests

These work in a similar way to GET requests, and you can initialize a request object with all of the available parameters for each endpoint.

Creating a customer

var customerRequest = new GoCardless.Services.CustomerCreateRequest()
{
    Email = "user@example.com",
    GivenName = "Frank",
    FamilyName = "Osborne",
    AddressLine1 = "27 Acer Road",
    AddressLine2 = "Apt 2",
    City = "London",
    PostalCode = "E8 3GX",
    CountryCode = "GB",
    Metadata = new Dictionary<string, string>()
    {
      {"salesforce_id", "ABCD1234"}
    }
};

var customerResponse = await gocardless.Customers.CreateAsync(customerRequest);
var customer = customerResponse.Customer;

Updating a customer

var customerRequest = new GoCardless.Services.CustomerUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"custom_reference", "NEWREFERENCE001"}
    }
};
var customerResponse = await gocardless.Customers.UpdateAsync("CU0123", customerRequest);

When creating a resource, the library will automatically include a randomly-generated idempotency key

• this means that if a request appears to fail but is in fact successful (for example due to a timeout), you will not end up creating multiple duplicates of the resource.

You can provide your own key for any endpoints that support idempotency keys by setting it in the request object:

var customerRequest = new GoCardless.Services.CustomerCreateRequest()
{
    Email = "user@example.com",
    IdempotencyKey = "unique_customer_reference"
};

Setting custom headers

You shouldn't generally need to customise the headers sent by the library, but you may wish to in some cases (for example if you want to send an Accept-Language header when creating a mandate PDF).

To do this, you can provide RequestSettings like this:

var requestSettings = new GoCardless.Internals.RequestSettings
{
    Headers = new Dictionary<string, string>()
    {
        {"Accept-Language", "fr"}
    }
};

var mandatePdfRequest = new GoCardless.Services.MandatePdfsCreateRequest()
{
    Iban = "FR14BARC20000055779911"
};

var mandatePdfResponse = await gocardless.MandatePdfs.CreateAsync(mandatePdfRequest, requestSettings);

Custom headers you specify will override any headers generated by the library itself (for example, an Authorization header with your configured access token or an Idempotency-Key header with a randomly-generated value or one you've configured manually). Custom headers always take precedence.

Accessing raw response data

You can retrieve the System.Net.Http.HttpResponseMessage from any resource or resource list response:

var customerRequest = new GoCardless.Services.CustomerUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"custom_reference", "NEWREFERENCE001"}
    }
};
var customerResponse = await gocardless.Customers.UpdateAsync("CU0123", customerRequest);

HttpResponseMessage responseMessage = customerResponse.ResponseMessage;

Errors

If the API returns an error response, the client will raise a corresponding Exception. The exceptions are all subclasses of GoCardless.Exceptions.ApiException:

• InternalException
• InvalidApiUsageException
• InvalidStateException
• ValidationFailedException

These errors are fully documented in the API documentation.

The exceptions have the following properties to facilitate access to information in the API response:

• string Type
• string DocumentationUrl
• string RequestId
• int Code
• IReadOnlyList<GoCardless.Errors.Error> Errors

GoCardless.Errors.Error provides more specific error messages and reasons from the response.

When the API returns an invalid_state error due to an idempotent_creation_conflict the library will, where possible, automatically retrieve the existing record which was created using the same idempotency key.

If a timeout occurs, and the request being made is idempotent, the library will automatically retry the request up to 2 more times.

Unless you pass your own HttpClient to GoCardlessClient.Create, requests are made with the shared GoCardlessClient.DefaultHttpClient, which times out after 100 seconds (the HttpClient default). To use a different timeout, pass an HttpClient with its Timeout set:

var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
var client = GoCardlessClient.Create(accessToken, Environment.SANDBOX, httpClient);

Handling webhooks

GoCardless supports webhooks, allowing you to receive real-time notifications when things happen in your account, so you can take automatic actions in response, for example:

• When a customer cancels their mandate with the bank, suspend their club membership
• When a payment fails due to lack of funds, mark their invoice as unpaid
• When a customer's subscription generates a new payment, log it in their "past payments" list

The client allows you to validate that a webhook you receive is genuinely from GoCardless, and to parse it into Event objects which are easy to work with:

// When you create a webhook endpoint, you can specify a secret. When GoCardless sends
// you a webhook, it will sign the body using that secret. Since only you and GoCardless
// know the secret, you can check the signature and ensure that the webhook is truly
// from GoCardless.
var webhookEndpointSecret = Environment.GetEnvironmentVariable("GOCARDLESS_WEBHOOK_ENDPOINT_SECRET");

// In your webhook handler
[HttpPost("/webhooks")]
public IActionResult HandleWebhook()
{
    var requestBody = new StreamReader(Request.Body).ReadToEnd();
    var signatureHeader = Request.Headers["Webhook-Signature"];

    try
    {
        var events = WebhookParser.Parse(requestBody, webhookEndpointSecret, signatureHeader);

        foreach (var webhookEvent in events)
        {
            Console.WriteLine(webhookEvent.Id);
        }

        return Ok();
    }
    catch (InvalidSignatureException)
    {
        // The webhook doesn't appear to be genuinely from GoCardless
        return StatusCode(498);
    }
}

Accessing the webhook ID

If you need to access the webhook ID for debugging purposes, you can use ParseWithMeta instead:

var result = WebhookParser.ParseWithMeta(requestBody, webhookEndpointSecret, signatureHeader);
var events = result.Events;
var webhookId = result.WebhookId;  // e.g. "WB123" - useful for debugging

Note: The webhook ID is intended for debugging and logging purposes only. It should not be used for deduplication - instead, use the event IDs to deduplicate, as each event has a unique ID that remains consistent if the same event is sent multiple times.

For more details on working with webhooks, see our "Getting started" guide.