README.md

.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 7.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 = "[email protected]",
    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 = "[email protected]",
    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.

Support and feedback

• Developer documentation
• Developer support
• [email protected]