For full details of the GoCardless API, see the API docs.
To install GoCardless
, run the following command in the Package Manager Console
Install-Package GoCardless -Version 7.0.0
Note: This README will use "customers" in examples throughout, but every endpoint in the API is available in this library.
The client is initialised with an access token and an environment.
var accessToken = "your_access_token";
var gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);
You can retrieve individual resources by ID using that resource's GetAsync
method:
var customerResponse = await gocardless.Customers.GetAsync("CU0123");
var customer = customerResponse.Customer;
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.
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"
};
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.
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;
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.