Buckaroo .NET implementation

Buckaroo .NET implementation


Oscar de Vaal

Buckaroo offers a simple solution for implementing iDeal payments on your website. In order to make use of the Buckaroo implementation, we need to write some code and apply configurations inside the portal (https://plaza.buckaroo.nl/)

The application flow

Before we start programming, let’s get a clear picture of the payment process.
For example, the user has filled in some forms and wants to pay. When the user submits the form, we will redirect the user to the iDeal payment page of Buckaroo. Two events will happen after this step:

  • The user will be redirected back to our website.
  • Buckaroo will notify our WebApp whether the payment has been successful.


In order to correctly redirect the user to Buckaroo, we need to use the Buckaroo SDK to generate a URL. Because we want the user to be redirected back to the correct page on our website, we need to provide Buckaroo with the correct return URLs.

After the user is redirected from Buckaroo back to our website, Buckaroo calls an endpoint on our website to persist the data of the transaction. Buckaroo will notify us if the payment is successful or not. Another useful feature is that the Buckaroo SDK enables us to provide custom parameters before redirecting the user to Buckaroo, that will be sent back to our endpoint. This is necessary for determining who has completed that particular transaction.

Setting up the portal

Luckily there is not a lot of configuration involved. We need the website key and we need to create a secret key. These two keys are needed in the next section when we implement the code.

Buckaroo website

Buckaroo secret

We can send custom parameters towards Buckaroo, so we can match the payment with the user. In order for Buckaroo to receive these custom parameters, we need to register these inside the portal.

Buckaroo Custom velden

Implementing the code

First, let’s download the BuckarooSDK package via NuGet (https://www.nuget.org/packages/BuckarooSDK/)

The following code will call the Buckaroo API with all the necessary parameters. We provide it with the two keys from the previous step, indicate if it’s a live or test payment and our custom parameters. We also send the URLs where the user will be redirected to after the payment and the URLs for our endpoints, whether the payment was successful or not.

After creating the request, the Buckaroo API will provide us with a unique URL. This way there is no data visible in the URL and the user cannot tamper with the payment process.

using System;
using System.Configuration;
using System.Globalization;
using System.Threading.Tasks;
using System.Web.Mvc;
using BuckarooSdk;
using BuckarooSdk.DataTypes;
using BuckarooSdk.DataTypes.RequestBases;
using BuckarooSdk.DataTypes.Response;
using BuckarooSdk.Logging;
using BuckarooSdk.Services.Ideal.TransactionRequest;
using HttpPostAttribute = System.Web.Mvc.HttpPostAttribute;

public class PaymentController : Controller

    public ActionResult Ideal()
        var websiteKey = ConfigurationManager.AppSettings["BuckarooWebsiteKey"];
        var secretKey = ConfigurationManager.AppSettings["BuckarooSecretKey"];
        var isLivePayment = "true".Equals(ConfigurationManager.AppSettings["BuckarooLivePayment"], StringComparison.OrdinalIgnoreCase);
        var ipAddress = Request.UserHostAddress;
        var logger = new StandardLogger();
        var client = new SdkClient(() => logger);
        var transactionBase = new TransactionBase
            Currency = "EUR",
            Invoice = "My invoice",
            Description = "My description",
            ReturnUrl = "https://www.yoursite.com/success",
            ReturnUrlReject = "https://www.yoursite.com/rejected",
            ReturnUrlCancel = "https://www.yoursite.com/canceled",
            ReturnUrlError = "https://www.yoursite.com/error",
            PushUrl = "https://www.yoursite.com/buckarooendpoint",
            PushUrlFailure = "https://www.yoursite.com/buckarooendpoint/failed",
            Order = "My order",
            AmountDebit = 12.5m, 
            ClientIp = new IpAddress { Type = 0, Address = ipAddress },
            ContinueOnIncomplete = ContinueOnIncomplete.RedirectToHTML

        transactionBase.AddCustomParameter("city", "Amsterdam");
        transactionBase.AddCustomParameter("zipcode", "1114BC");
        transactionBase.AddCustomParameter("housenumber", "7");
        transactionBase.AddCustomParameter("firstname", "Oscar");
        transactionBase.AddCustomParameter("lastname", "de Vaal");

        var request = client
            .Authenticate(websiteKey, secretKey, isLivePayment, CultureInfo.GetCultureInfo("nl-nl"))
            .Pay(new IdealPayRequest());

        RequestResponse result = null;
        Task.Run(async () => result = await request.ExecuteAsync()).Wait();

        return Redirect(result.RequiredAction.RedirectURL);

After the payment, Buckaroo will call the URL that we have provided, along with a list of parameters. The unique identifier of the payment is the brq_transactions parameter. Our custom parameters are prefixed with “CUST_”.


I have created a model class for deserializing the data.

using Newtonsoft.Json;

public class BuckarooDto
    public string City { get; set; }

    public string PaymentId { get; set; }

    public string FirstName { get; set; }

    public string Housenumber { get; set; }

    public string LastName { get; set; }

    public string Zipcode { get; set; }

The following controller is an example of what the Endpoint can look like.

using System.Linq;
using System.Web.Mvc;
using Newtonsoft.Json;

public class BuckarooEndpointController : Controller
    public void Index()
        var buckarooDto = GetBuckarooDto();
        //Execute success code

    public void Failed()
        var buckarooDto = GetBuckarooDto();
        //Execute failed code

    private BuckarooDto GetBuckarooDto()
        var parameters = Request.Params
                k => k,
                v => Request.Params[v]);

        var json = JsonConvert.SerializeObject(parameters);
        return JsonConvert.DeserializeObject<BuckarooDto>(json);

In case our EndpointController throws an error, Buckaroo will try to call this Endpoint for another 10 times. The interval that Buckaroo will call our endpoint is:

  • 5 minutes
  • 10 minutes
  • 15 minutes
  • 30 minutes
  • 1 hour
  • 2 hours
  • 4 hours
  • 8 hours
  • 8 hours
  • 24 hours
  • 24 hours

It’s also possible to manually initiate this call from the portal.

The result

The user will be redirected to Buckaroo’s iDeal payment page.

Buckaroo iDeal

Oscar de Vaal

.NET Developer