> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# .NET

## Introduction

The Mangopay .NET SDK makes working with the Mangopay API easier in a .NET environment.

The SDK package is available on NuGet: <a href="https://www.nuget.org/packages/mangopay4-net-sdk" target="_blank">mangopay4-net-sdk</a>

<Warning>
  **Caution – Use only the mangopay4 package (late Nov 2025)**

  Please ensure you use **only** the package with **mangopay4** in the name (this is the package name and has no connection with the SDK version number).

  **Any other package must not be used.** You need to update your package manually.

  Since November 25, 2025, Mangopay's official SDKs are no longer accessible on GitHub (with the exception of PHP for publication reasons).
</Warning>

<Info>
  **Prerequisites**

  To run the Mangopay .NET SDK, you’ll need:

  * A `ClientId` and an API key – if you don't have these, <a href="https://mangopay.com/contact" target="_blank">contact Sales</a> to get access to the <a href="https://hub.mangopay.com/" target="_blank">Mangopay Dashboard</a>
  * .NET Standard 2.0 or .NET 6.0
  * Common.Logging library (version 3.4.1 or higher)
  * Newtonsoft.Json (version 13.0.1 or higher)
  * RestSharp (version 107.3.0 or higher)
  * NETStandard.Library (version 2.0.3 or higher)
</Info>

## Getting started

#### 1. Install the Mangopay package

Installation from the .NET Package Manager Console

```shell theme={null}
NuGet\Install-Package mangopay4-net-sdk
```

Installation with the .NET CLI

```shell theme={null}
dotnet add package mangopay4-net-sdk
```

#### 2. Initialize and configure the SDK

```csharp theme={null}
using MangoPay.SDK;
using MangoPay.SDK.Entities;
using System.Reflection;

class Program {
    static void Main(string[] args)
    {
        MangoPayApi api = new MangoPayApi();

        api.Config.ClientId = "your-client-id";
        api.Config.ClientPassword = "your-api-key";

	  ...

    }
}
```

The configuration object of the SDK supports all the following properties:

<table>
  <thead>
    <tr>
      <th class="header">Key</th>
      <th class="header">Type</th>
      <th class="header">Default value</th>
      <th class="header">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">`ClientId`</td>
      <td class="table-content">string</td>
      <td class="table-content">`null`</td>
      <td class="table-content">Your Mangopay ClientId – can be found in the <a href="https://hub.mangopay.com/" target="_blank">Dashboard</a>.</td>
    </tr>

    <tr>
      <td class="table-content">`ClientPassword`</td>
      <td class="table-content">string</td>
      <td class="table-content">`null`</td>
      <td class="table-content">Your Mangopay API key – can be found in the <a href="https://hub.mangopay.com/" target="_blank">Dashboard</a>.</td>
    </tr>

    <tr>
      <td class="table-content">`BaseUrl`</td>
      <td class="table-content">string</td>
      <td class="table-content">[https://api.sandbox.mangopay.com/v2.01/](https://api.sandbox.mangopay.com/v2.01/)</td>
      <td class="table-content">The API sandbox URL. Set to the sandbox environment by default. To enable production environment, set it to [https://api.mangopay.com](https://api.mangopay.com)</td>
    </tr>

    <tr>
      <td class="table-content">`Timeout`</td>
      <td class="table-content">integer</td>
      <td class="table-content">`0`</td>
      <td class="table-content">Time to wait in milliseconds while trying to establish a connection before terminating the attempt and generating an error.</td>
    </tr>

    <tr>
      <td class="table-content">`LoggerFactoryAdapter`</td>
      <td class="table-content">ILoggerFactoryAdapter</td>
      <td class="table-content">`NoOpLoggerFactoryAdapter()`</td>
      <td class="table-content">Logger adapter implementation. Disabled by default.</td>
    </tr>
  </tbody>
</table>

## SDK usage

In the Mangopay documentation, you'll find detailed information of all endpoints paired with its corresponding .NET SDK method implementation example. Be sure to customize the provided code to suit your specific requirements.

### Idempotency support

To make a request with idempotency support, add `idempotencyKey` parameter to your function.

For more information, see the <a href="/api-reference/overview/idempotency">Idempotency</a> article.

```csharp Call - Create user with idempotency key theme={null}
using MangoPay.SDK;
using MangoPay.SDK.Core.Enumerations;
using MangoPay.SDK.Entities;
using MangoPay.SDK.Entities.POST;
using System.Reflection;

class CreateUser
{
    static async Task Main(string[] args)
    {
        MangoPayApi api = new MangoPayApi();

        api.Config.ClientId = "your-client-id";
        api.Config.ClientPassword = "your-api-key";

        var myUser = new UserNaturalOwnerPostDTO
        {
            Tag = "Created using the Mangopay .NET SDK",
            Email = "alice.smith@example.com",
            FirstName = "Alice",
            LastName = "Smith",
            Address = new Address
            {
                AddressLine1 = "17 Rue de la République",
                City = "Paris",
                PostalCode = "75001",
                Country = CountryIso.FR
            },
            Birthday = new DateTime(1985, 3, 15),
            Nationality = CountryIso.FR,
            CountryOfResidence = CountryIso.FR
        };

        var idempotencyKey = "pk7urhkW55KpTHf44567-d";

        var createNaturalUser = await api.Users.CreateOwnerAsync(myUser, idempotencyKey);

        foreach (PropertyInfo prop in createNaturalUser.GetType().GetProperties())
        {
            var propValue = prop.GetValue(createNaturalUser);
            if (propValue != null)
            {
                Console.Write($"{prop.Name}: ");

                if (prop.Name == "Address")
                {
                    var address = propValue as Address;
                    if (address != null)
                    {
                        Console.WriteLine($"{address.AddressLine1}, {address.AddressLine2}, {address.City}, {address.PostalCode}, {address.Country}");
                    }
                }
                else
                {
                    Console.WriteLine(propValue);
                }
            }
        }
    }
}
```

In order to retrieve the request made using the idempotency key:

```csharp Call - View API Response theme={null}
using MangoPay.SDK;
using System.Reflection;

class ViewResponse
{
    static async Task Main(string[] args)
    {
        MangoPayApi api = new MangoPayApi();

        api.Config.ClientId = "your-client-id";
        api.Config.ClientPassword = "your-api-key";

        var idempotencyKey = "pk7urhkW55KpTHf44567-d";
        
        var result = await api.Idempotent.GetAsync(idempotencyKey);

        foreach (PropertyInfo prop in result.GetType().GetProperties())
        {
            var propValue = prop.GetValue(result);
            if (propValue != null)
            {
                Console.Write($"{prop.Name}: ");
                Console.WriteLine(propValue);                   
            }
        }
    }
}
```

```csharp Output theme={null}
StatusCode: 200
ContentLength: 717
ContentType: application/json; charset=utf-8
Date: Fri, 22 Mar 2024 14:13:38 GMT
RequestURL: https://api.sandbox.mangopay.com/v2.01/your-client-id/users/natural
Resource: MangoPay.SDK.Entities.GET.UserNaturalDTO
CreationDate: 1/1/0001 12:00:00 AM
```

### Pagination

For endpoints that support <a href="/api-reference/overview/pagination">pagination</a>, you can use the `Pagination` object. 

In the object, you need to specify the page and items per page to return.

As a result, the answer will be paginated, and the total number of items and the total number of pages will be provided.

For example, with the <a href="/api-reference/users/list-users">GET List all Users</a> endpoint
:

```csharp theme={null}
using MangoPay.SDK;
using MangoPay.SDK.Entities;
using System.Reflection;

class ListAllUsers {
    static async Task Main(string[] args)
    {
        MangoPayApi api = new MangoPayApi();

        api.Config.ClientId = "your-client-id";
        api.Config.ClientPassword = "your-api-key";

        var myUsers = await api.Users.GetAllAsync(new Pagination(1, 100));

        foreach (var user in myUsers)
        {
            foreach (PropertyInfo prop in user.GetType().GetProperties())
            {
                var propValue = prop.GetValue(user);
                if (propValue != null)
                {
                    Console.Write($"{prop.Name}: ");
                    Console.WriteLine(propValue);
                }
            }
            Console.WriteLine();
        }
    }
}
```

### Rate limiting status

Rate limiting in Mangopay restricts the frequency of API requests a client can make over a defined period, automatically updating the limit with each request and blocking additional requests if the limit is exceeded until it resets. For more information, see the <a href="/api-reference/overview/rate-limiting">rate limiting</a> article.

```csharp Call - View a user theme={null}
using MangoPay.SDK;
using MangoPay.SDK.Entities;
using RestSharp;
using System.Reflection;

class ViewUser
{
    static async Task Main(string[] args)
    {
        MangoPayApi api = new MangoPayApi();

        api.Config.ClientId = "your-client-id";
        api.Config.ClientPassword = "your-api-key";

        var myUser = await api.Users.GetNaturalAsync("user_m_01HRCAJT98VPWE4DHBTC8N8KA0");
        var response = await Task.Run(() => api.LastRequestInfo);

        Console.WriteLine($"Method: {response.Request.Method}");
        Console.WriteLine($"Resource: {response.Request.Resource}");
        Console.WriteLine("Headers:");
        foreach (var header in response.Request.Parameters.Where(p => p.Type == ParameterType.HttpHeader))
        {
            Console.WriteLine($"{header.Name}: {header.Value}");
        }
        var requestBody = response.Request.Parameters.FirstOrDefault(p => p.Type == ParameterType.RequestBody)?.Value;
        if (!string.IsNullOrEmpty((string?)requestBody))
        {
            Console.WriteLine($"Body: {requestBody}");
        }

        // Display Response details
        Console.WriteLine("\nResponse Details:");
        Console.WriteLine($"Response type: {response.Response.GetType().FullName}");
        foreach (PropertyInfo prop in response.GetType().GetProperties())
        {
            var propValue = prop.GetValue(response);
            Console.Write($"{prop.Name}: ");
            Console.WriteLine(propValue);
        }

        foreach (PropertyInfo prop in myUser.GetType().GetProperties())
        {
            var propValue = prop.GetValue(myUser);
            if (propValue != null)
            {
                Console.Write($"{prop.Name}: ");

                if (prop.Name == "Address")
                {
                    var address = propValue as Address;
                    if (address != null)
                    {
                        Console.WriteLine($"{address.AddressLine1}, {address.AddressLine2}, {address.City}, {address.PostalCode}, {address.Country}");
                    }
                }
                else
                {
                    Console.WriteLine(propValue);
                }
            }
        }
    }
}
```

```csharp Output theme={null}
Method: Get
Resource: /v2.01/your-client-id/users/natural/user_m_01HRCAJT98VPWE4DHBTC8N8KA0
Headers:
User-Agent: MangoPay V2 SDK .NET 3.16.0.0
Authorization: bearer f8cc4ce612524a11afac04abbf0798d6

Response Details:
Response type: RestSharp.RestResponse`1[[MangoPay.SDK.Entities.GET.UserNaturalDTO, MangoPay.SDK, Version=3.16.0.0, Culture=neutral, PublicKeyToken=null]]
Request: RestSharp.RestRequest
Response: RestSharp.RestResponse`1[MangoPay.SDK.Entities.GET.UserNaturalDTO]
RateLimitingCallsAllowed: 
RateLimitingCallsRemaining: 2294
RateLimitingTimeTillReset: 1711642500
FirstName: Alice
LastName: Smith
Address: 17 Rue de la République, , Paris, 75001, FR
Birthday: 3/15/1985 12:00:00 AM
Nationality: FR
CountryOfResidence: FR
TermsAndConditionsAccepted: False
UserCategory: OWNER
PersonType: NATURAL
Email: alice.smith@example.com
KYCLevel: LIGHT
Id: user_m_01HRCAJT98VPWE4DHBTC8N8KA0
Tag: Created using the Mangopay .NET SDK
CreationDate: 3/7/2024 11:25:39 AM
```

### Unit tests

All unit tests are placed under the MangoPay.SDK.Tests directory.

## Error handling

The SDK provides the `ResponseException` class to wrap HTTP errors returned by the API. You can use a standard `try-catch` block to target the class and add your custom logic, for example:

```csharp theme={null}
try
{
   await this.Api.Wallets.GetAsync(wallet.Id, "USER_PRESENT");
}
catch (ResponseException ex)
{
   // use ex details for custom logic
}
```