https://github.com/gocardless/gocardless-dotnet
GoCardless .NET Client
https://github.com/gocardless/gocardless-dotnet
Last synced: about 1 year ago
JSON representation
GoCardless .NET Client
- Host: GitHub
- URL: https://github.com/gocardless/gocardless-dotnet
- Owner: gocardless
- License: mit
- Created: 2016-09-28T17:18:04.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2025-04-04T10:04:37.000Z (over 1 year ago)
- Last Synced: 2025-04-06T10:03:22.954Z (about 1 year ago)
- Language: C#
- Homepage: https://developer.gocardless.com/api-reference/?lang=dotnet
- Size: 1.32 MB
- Stars: 28
- Watchers: 67
- Forks: 15
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# .NET Client for the GoCardless API
For full details of the GoCardless API, see the [API docs](https://developer.gocardless.com/).
[](https://www.nuget.org/packages/GoCardless/)
[](https://github.com/gocardless/gocardless-dotnet/actions)
- ["Getting started" guide](https://developer.gocardless.com/getting-started/api/introduction/)
- [API Reference](https://developer.gocardless.com/api-reference)
- [NuGet Package](https://www.nuget.org/packages/GoCardless/)
## Installation
To install `GoCardless`, run the following command in the [Package Manager Console](https://docs.microsoft.com/en-us/nuget/tools/package-manager-console)
`Install-Package GoCardless -Version 7.7.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.
```cs
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:
```cs
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`:
```cs
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`:
```cs
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*
```cs
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()
{
{"salesforce_id", "ABCD1234"}
}
};
var customerResponse = await gocardless.Customers.CreateAsync(customerRequest);
var customer = customerResponse.Customer;
```
*Updating a customer*
```cs
var customerRequest = new GoCardless.Services.CustomerUpdateRequest()
{
Metadata = new Dictionary()
{
{"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](https://developer.gocardless.com/api-reference/#making-requests-idempotency-keys)
- 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:
```cs
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](https://developer.gocardless.com/api-reference/#mandate-pdfs-create-a-mandate-pdf)).
To do this, you can provide `RequestSettings` like this:
```cs
var requestSettings = new GoCardless.Internals.RequestSettings
{
Headers = new Dictionary()
{
{"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:
```cs
var customerRequest = new GoCardless.Services.CustomerUpdateRequest()
{
Metadata = new Dictionary()
{
{"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](https://developer.gocardless.com/api-reference/#overview-errors).
The exceptions have the following properties to facilitate access to information in the API response:
- `string Type`
- `string DocumentationUrl`
- `string RequestId`
- `int Code`
- `IReadOnlyList 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](https://developer.gocardless.com/)
- [Developer support](https://support.gocardless.com/hc/en-us/categories/115000140449)
- api@gocardless.com