01. Getting started

Installing the library

The easiest way to install the Mollie Api library is to use the Nuget Package.

Install-Package Mollie.Api

Creating a API client

Every API has it's own API client class. For example: PaymentClient, PaymentMethodClient, CustomerClient, MandateClient, SubscriptionClient, IssuerClient and RefundClient classes. All of these API client classes also have their own interface. The recommended way to instantiate API clients, is to use the built in dependency injection extension method:

builder.Services.AddMollieApi(options => {
    options.ApiKey = builder.Configuration["Mollie:ApiKey"];
    options.RetryPolicy = MollieHttpRetryPolicies.TransientHttpErrorRetryPolicy();
});

Alternatively, you can create the API client manually using the constructor. All API clients require a api/oauth key in the constructor and you can also pass in an optional HttpClient object. If you do not pass a HttpClient object, one will be created automatically. In the latter case, you are responsible for disposing the API client by calling the Dispose() method on the API client object or by using a using statement.

using IPaymentClient paymentClient = new PaymentClient("{yourApiKey}", new HttpClient());

Multi-tenant setup

For multi-tenant setups, you can create and configure a custom implementation of the IMollieSecretManager interface. For example:

builder.Services.AddMollieApi(options => {
    options.SetCustomMollieSecretManager<TenantSecretManager>();
    options.RetryPolicy = MollieHttpRetryPolicies.TransientHttpErrorRetryPolicy();
});

Custom secret manager for multi-tenant setup:

public class TenantSecretManager : IMollieSecretManager {
    private readonly ITenantService _tenantService;

    public string GetBearerToken() => _tenantService.GetCurrentTenant().ApiKey;
}

Example projects

An example ASP.NET Core web application project is included. In order to use this project you have to set your Mollie API key in the appsettings.json file. The example project demonstrates the Payment API, Mandate API, Customer API and Subscription API.

Testing

During the process of building your integration, it is important to properly test it. You can access the test mode of the Mollie API in two ways: by using the Test API key, or, if you are using organization access tokens or app tokens, by providing the testmode parameter in your API request. If you are using the Test API key, you do not have to set the testmode parameter anywhere. Any entity you create, retrieve, update or delete using a Test API key can only interact with the test system of Mollie, which is completely isolated from the production environment.

Using the webhook on your local development machine

In the example project, you can also find a webhook example in the PaymentController.cs. In order for this endpoint to be called by the webhook, it needs to be exposed to the internet using a HTTP tunnel such as ngrok. Setting up ngrok is quite easy and can be done using the following steps:

1. Install ngrok
2. Start ngrok with the following command: ngrok http https://localhost:{your-https-port}
3. Copy the ngrok forwarding URL

4. Create a new payment in the example app and set the webhook URL to the ngrok forwarding url. Don't forget to append the /api/payment route.

5. Perform an action that will cause the payment status to be updated. For example, by paying the the payment or cancelling it.

Idempotency and retrying requests

When issuing requests to an API, there is always a small chance of issues on either side of the connection. For example, the API may not respond to the request within a reasonable timeframe. Your server will then consider the request to have ‘timed out’. However, your request may still arrive at the API eventually and get executed, despite your server considering it a timeout.

Mollie supports the Idempotency-Key industry standard. When sending a request to the Mollie API, you can send along a header with a unique value. If another request is made with the exact same header value within one hour, the Mollie API will return a cached version of the initial response. This way, your API requests become what we call idempotent. Read more on this in the Mollie documentation on Idempotency

The library automatically generates a unique GUID for each request and adds it to the Idempotency-Key header. Using a transient fault handling library such as Polly, you are able to automatically retry requests in case of a timeout or 5xx status code error using the following example code:

using Polly;
using Polly.Extensions.Http;

public static class MollieApiClientServiceExtensions {
        public static IServiceCollection AddMollieApi(this IServiceCollection services, IConfiguration configuration) {
		MollieConfiguration mollieConfiguration = configuration.GetSection("Mollie").Get<MollieConfiguration>();
            
            	services.AddHttpClient<IPaymentClient, PaymentClient>(httpClient => new PaymentClient(mollieConfiguration.ApiKey, httpClient))
                	.AddPolicyHandler(GetDefaultRetryPolicy());
	}
	
	static IAsyncPolicy<HttpResponseMessage> GetDefaultRetryPolicy() {
            return HttpPolicyExtensions
	    	// Timeout errors or 5xx static code errors
                .HandleTransientHttpError() 
		// Requests are retried three times, with different intervals
                .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2,
                    retryAttempt)));
        }
}

It is also possible to specify your own custom idempotency key when sending requests. All requests within the using block will be sent using the custom idempotency key configured in the WithIdempotencyKey method.

PaymentRequest paymentRequest = new PaymentRequest() {
	Amount = new Amount(Currency.EUR, "100.00"),
	Description = "Description",
	RedirectUrl = DefaultRedirectUrl
};

using (_paymentClient.WithIdempotencyKey("my-idempotency-key"))
{
	PaymentResponse response = await _paymentClient.CreatePaymentAsync(paymentRequest);
}

List of constant value strings

In the past, this library used enums that were decorated with the EnumMemberAttribute for static values that were defined in the Mollie documentation. We have now moved away from this idea and are using constant strings everywhere. The reason for this is that enum values often broke when Mollie added new values to their API. This means that I had to release a new version every time when Mollie added a new value and all library consumers had to update their version. The following static classes are available with const string values that you can use to set and compare values in your code:

• Mollie.Api.Models.Payment.PaymentMethod
• Mollie.Api.Models.Payment.PaymentStatus
• Mollie.Api.Models.Payment.SequenceType
• Mollie.Api.Models.Payment.Request.KbcIssuer
• Mollie.Api.Models.Payment.Response.CreditCardAudience
• Mollie.Api.Models.Payment.Response.CreditCardSecurity
• Mollie.Api.Models.Payment.Response.CreditCardFailureReason
• Mollie.Api.Models.Payment.Response.CreditCardLabel
• Mollie.Api.Models.Payment.Response.CreditCardFeeRegion
• Mollie.Api.Models.Payment.Response.PayPalSellerProtection
• Mollie.Api.Models.Mandate.InvoiceStatus
• Mollie.Api.Models.Mandate.MandateStatus
• Mollie.Api.Models.Order.OrderLineDetailsCategory
• Mollie.Api.Models.Order.OrderLineDetailsType
• Mollie.Api.Models.Order.OrderLineStatus
• Mollie.Api.Models.Order.OrderStatus
• Mollie.Api.Models.Order.OrderLineOperation
• Mollie.Api.Models.Profile.CategoryCode
• Mollie.Api.Models.Profile.ProfileStatus
• Mollie.Api.Models.Refund.RefundStatus
• Mollie.Api.Models.Settlement.SettlementStatus
• Mollie.Api.Models.Subscription.SubscriptionStatus
• Mollie.Api.Models.Connect.AppPermissions
• Mollie.Api.Models.Onboarding.Response.OnboardingStatus
• Mollie.Api.Models.Balance.Response.BalanceReport.ReportGrouping
• Mollie.Api.Models.Balance.Response.BalanceTransaction.BalanceTransactionContextType
• Mollie.Api.Models.Payment.Locale
• Mollie.Api.Models.Currency
• Mollie.Api.Models.CompanyEntityType

You can use these classes similar to how you use enums. For example, when creating a new payment, you can do the following:

PaymentRequest paymentRequest = new PaymentRequest() {
    Amount = new Amount(Currency.EUR, 100.00m),
    Description = "Test payment of the example project",
    RedirectUrl = "http://google.com",
	Method = Mollie.Api.Models.Payment.PaymentMethod.Ideal // instead of "Ideal"
};