SpareApi 0.0.1

SpareApi .NET SDK

The official .NET / C# SDK for the SpareApi Open Banking API.

Table of Contents

• Installation
• Versioning
• Getting Started
  • Configuration
  • Configuration options
  • Multi-environment support
• Error Handling
• Examples
  • List providers
  • Create a payment request
  • Check payment consent status
  • Get a payment
  • Register a bank account
  • Schedule a mandate
  • Verify a beneficiary
  • List saved debtor accounts
  • Request signing (x-signature)
• Contributing
• License

Installation

dotnet add package SpareApi

Requires .NET 6.0 or later. The package is available on NuGet.

Versioning

The SDK follows Semantic Versioning. Breaking changes are indicated by a major version bump. The changelog is available on the GitHub releases page.

All users are strongly recommended to use a recent version of the library, as older versions may not contain support for new endpoints and fields.

Getting Started

Configuration

using SpareApi;

// 1. Create a Configuration with your credentials
var config = new Configuration(new ConfigurationOptions
{
    AppId  = Environment.GetEnvironmentVariable("SPARE_APP_ID")!,
    ApiKey = Environment.GetEnvironmentVariable("SPARE_API_KEY")!,
    Tenant = Environment.GetEnvironmentVariable("SPARE_TENANT")!,
});

// 2. Pass it to the client — that's it
var client = new SpareApiClient(config);

// Token exchange happens automatically on the first request.
// X-Tenant header is injected on every request.
var providers = await client.Providers.ListAsync(
    new ListProvidersRequest { CountryCode = "AE" }
);
foreach (var provider in providers.Data)
{
    provider.Switch(
        ksa => Console.WriteLine($"{ksa.Id} {ksa.EnglishName}"),
        bahrain => Console.WriteLine($"{bahrain.Id} {bahrain.EnglishName}"),
        uae => Console.WriteLine($"{uae.Id} {uae.Name}")
    );
}

Required environment variables:

Configuration options

Multi-environment support

// Sandbox (default)
var sandboxConfig = new Configuration(new ConfigurationOptions
{
    AppId = "...", ApiKey = "...", Tenant = "UAE",
    Environment = SpareEnvironment.Sandbox,
});

// Production
var productionConfig = new Configuration(new ConfigurationOptions
{
    AppId = "...", ApiKey = "...", Tenant = "UAE",
    Environment = SpareEnvironment.Production,
});

// Local development
var localConfig = new Configuration(new ConfigurationOptions
{
    AppId = "...", ApiKey = "...", Tenant = "UAE",
    BaseUrl = "http://localhost:4000",   // overrides Environment
});

Error Handling

All non-2xx responses throw a SpareApiApiException. Inspect StatusCode and Body to handle specific error types:

using SpareApi;

try
{
    var consent = await client.PaymentConsents.GetAsync(
    new GetPaymentConsentsRequest { ConsentId = "consent-id" }
);
}
catch (SpareApiApiException e)
{
    Console.Error.WriteLine(e.StatusCode); // HTTP status — e.g. 404
    Console.Error.WriteLine(e.Body);       // raw response body
    throw;
}

Examples

For more examples see the API reference documentation.

List providers

Retrieve the open-banking providers available in a given country:

var providers = await client.Providers.ListAsync(
    new ListProvidersRequest { CountryCode = "AE" }
);

foreach (var provider in providers.Data)
{
    provider.Switch(
        ksa => Console.WriteLine($"{ksa.Id} {ksa.EnglishName}"),
        bahrain => Console.WriteLine($"{bahrain.Id} {bahrain.EnglishName}"),
        uae => Console.WriteLine($"{uae.Id} {uae.Name}")
    );
}

Create a payment request

Payment requests require a request signature. Use client.Crypto.SignPayload to produce the ES256 detached JWS and pass it as Signature:

var body = new Dictionary<string, object>
{
    ["type"]              = "SingleInstantPayment",
    ["purpose"]           = "ACM",
    ["creditorType"]      = "MERCHANT",
    ["creditorReference"] = "INV-10042",
    ["creditorAccount"]   = new Dictionary<string, object>
    {
        ["identification"] = "AE070331234567890123456",
        ["name"]           = "Acme Corp",
        ["schemeName"]     = "IBAN",
    },
    ["instructions"] = new Dictionary<string, object>
    {
        ["amount"] = new Dictionary<string, object>
        {
            ["amount"]   = "250.00",
            ["currency"] = "AED",
        },
    },
};

var xSignature = client.Crypto.SignPayload(
    Environment.GetEnvironmentVariable("SPARE_PRIVATE_KEY_PEM")!, body);

var paymentRequest = await client.PaymentRequests.CreateAsync(
    new CreatePaymentRequestsRequest
    {
        Type = "SingleInstantPayment",
        Purpose = "ACM",
        CreditorType = "MERCHANT",
        CreditorReference = "INV-10042",
        MerchantReference = "INV-10042",
        CreditorAccount = new CreatePaymentRequestsRequestCreditorAccount
        {
            Identification = "AE070331234567890123456",
            Name = "Acme Corp",
            SchemeName = "IBAN",
        },
        Instructions = new PaymentIPaymentInstructionsUae
        {
            Amount = new PaymentIAmountDtoUae { Amount = "250.00", Currency = "AED" },
        },
        Signature = xSignature,
    }
);

Console.WriteLine($"Payment request: {paymentRequest.Data.Id}");
// Redirect the user to this URL to authorise the payment at their bank
Console.WriteLine($"Authorise at: {paymentRequest.Data.RedirectUrl}");

Check payment consent status

After the user authorises at the bank (via RedirectUrl), consent is created server-side. Poll or sync status using PaymentConsents.ListAsync, PaymentConsents.GetAsync, or PaymentConsents.SyncAsync:

// List all consents (paginated)
var consents = await client.PaymentConsents.ListAsync(
    new ListPaymentConsentsRequest { Page = 1, PerPage = 10 }
);
foreach (var c in consents.Data)
{
    Console.WriteLine($"{c.Id} {c.Status}");
}

// Get a specific consent by ID
var consent = await client.PaymentConsents.GetAsync(
    new GetPaymentConsentsRequest { ConsentId = "consent-id" }
);
Console.WriteLine($"Consent status: {consent.Data.Status}");

// Force a sync from the bank to get the latest status
var synced = await client.PaymentConsents.SyncAsync(
    new SyncPaymentConsentsRequest { PaymentRequestId = paymentRequest.Data.Id }
);
Console.WriteLine($"Synced status: {synced.Data.Status}");

Get a payment

var payment = await client.Payments.GetAsync(
    new GetPaymentsRequest { PaymentId = paymentId }
);

Console.WriteLine($"Status: {payment.Data.Status}");

Register a bank account

var account = await client.BankAccounts.CreateAsync(
    new CreateBankAccountsRequest
    {
        AccountDetails = new CreateBankAccountsRequestAccountDetails
        {
            IdentificationNumber = "AE070331234567890123456",
            Scheme = "IBAN",
        },
        AccountHolderDetails = new CreateBankAccountsRequestAccountHolderDetails
        {
            Name = "Acme Corp",
        },
        Name = "Primary settlement account",
    }
);

Console.WriteLine($"Account registered: {account.Data.Id}");

Schedule a mandate

Scheduling a mandate also requires a request signature:

var mandateBody = new Dictionary<string, object>
{
    ["mandateId"]     = "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    ["amount"]        = 500,
    ["executionDate"] = "2025-06-01",
};

var xSignature = client.Crypto.SignPayload(
    Environment.GetEnvironmentVariable("SPARE_PRIVATE_KEY_PEM")!, mandateBody);

var mandate = await client.Mandates.ScheduleAsync(
    new ScheduleMandatesRequest
    {
        MandateId     = "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        Amount        = 500,
        ExecutionDate = "2025-06-01",
        Signature    = xSignature,
    }
);

Console.WriteLine($"Mandate scheduled: {mandate.Data.Id}");

Verify a beneficiary

Confirm that a beneficiary account (IBAN) matches the expected name before creating a payment, to reduce misdirected-payment risk. No request signature is required.

var verification = await client.Verifications.VerifyBeneficiaryAsync(
    new VerifyBeneficiaryVerificationsRequest
    {
        Iban = "AE070331234567890123456",
        BeneficiaryName = "Acme Corp",
    }
);

Console.WriteLine($"Result: {verification.Data.Result}");
Console.WriteLine($"Matched name: {verification.Data.BeneficiaryName}");

List saved debtor accounts

Debtor (payer) accounts saved against one of your end-customers. The end-customer is identified by the required CustomerId header (a merchant-supplied UUID).

var accounts = await client.SavedDebtorAccounts.ListAsync(
    new ListSavedDebtorAccountsRequest
    {
        CustomerId = Environment.GetEnvironmentVariable("SPARE_CUSTOMER_ID")!,
        Page = 1,
        PerPage = 20,
    }
);

foreach (var account in accounts.Data)
{
    Console.WriteLine($"{account.Id} {account.MaskedIdentification}");
}

Request signing (x-signature)

Certain endpoints — PaymentRequests.CreateAsync and Mandates.ScheduleAsync — require a detached JWS signature, passed via the Signature field. The SDK ships a CryptoHelper accessible via client.Crypto.

Generate a key pair and register the public key in your Spare dashboard:

openssl ecparam -genkey -name prime256v1 -noout | openssl pkcs8 -topk8 -nocrypt -out private.pem
openssl ec -in private.pem -pubout -out public.pem   # register public.pem in dashboard

Using CryptoHelper standalone:

using SpareApi;

var crypto = new CryptoHelper();

// Canonical JSON (sorted keys, nulls omitted)
var canonical = crypto.SerializePayload(body);
Console.WriteLine("Canonical: " + canonical);

// ES256 detached JWS — pass as Signature (x-signature header)
var privateKeyPem = Environment.GetEnvironmentVariable("SPARE_PRIVATE_KEY_PEM")!;
var xSignature = crypto.SignPayload(privateKeyPem, body);
Console.WriteLine("x-signature: " + xSignature);  // eyJhbGciOiJFUzI1NiJ9...<sig>

Contributing

See CONTRIBUTING.md.

License

This SDK is distributed under the MIT License.