.NET SDK

Use the Raims package to integrate a server application written in C# with the public API. The SDK provides resource services, typed inputs and responses, cursor pagination, and webhook signature verification. Methods have synchronous and asynchronous variants, with the Async suffix.

The integration requires an x64 application running .NET Framework 4.8/4.8.1 or .NET 10. Do not distribute the API key in browser, desktop, or mobile apps provided to your customers. Keep it in the integration backend.

Install the package

From your application directory:

dotnet add package Raims

Without a version argument, NuGet installs the latest stable version compatible with the project and records the reference in your application.

The package targets netstandard2.0 and net10.0. NuGet selects the appropriate target; supported consumers are validated on x64 .NET Framework 4.8 and .NET 10.

Configure the client

Obtain a key through API keys and store it in a protected environment variable or your application's secret store. The validated credential determines the company, environment, and permissions in the API. Sandbox and Production use https://api.raims.com.

This example is a snippet for an async method:

using System;
using Raims;

string apiKey = Environment.GetEnvironmentVariable("RAIMS_API_KEY")
    ?? throw new InvalidOperationException("Configure RAIMS_API_KEY.");

using (var raims = new RaimsClient(apiKey))
{
    var customers = await raims.Customers.ListAsync(new ListCustomersOptions
    {
        PageSize = 20,
    });

    foreach (var customer in customers)
    {
        Console.WriteLine(customer.Id);
    }
}

Reuse the client for the integration's lifetime to reuse HTTP connections, and dispose it when no longer needed. The following snippets assume a raims instance configured by your application.

Create a customer and a charge

customerTaxId is the valid CPF or CNPJ of a customer authorized by your application. customerIdempotencyKey and chargeIdempotencyKey are separate keys created and persisted before the requests. chargeDueDate is the due date chosen and persisted for the order, expressed as UTC Unix seconds.

var customer = await raims.Customers.CreateAsync(new CreateCustomerOptions
{
    TaxId = customerTaxId,
}, new RequestOptions { IdempotencyKey = customerIdempotencyKey });

var charge = await raims.Charges.CreateAsync(new CreateChargeOptions
{
    CustomerId = customer.Id,
    AmountCents = 15000,
    DueDate = chargeDueDate,
    Title = "Order 1234",
}, new RequestOptions { IdempotencyKey = chargeIdempotencyKey });

int? httpStatus = charge.LastResponse?.StatusCode;
var requestId = charge.LastResponse?.RequestId;

If the CPF or CNPJ already exists in the same company and environment, the customer record is updated and retains its identifier. 15000 represents BRL 150.00. Review the fields and conditions in Create a charge. To retry the same intent after a lost response, keep the key and every parameter, including the due date. An external order reference does not replace idempotency.

Pagination and pending results

Enumerating one page does not make additional requests. Use NextPageAsync() and PreviousPageAsync() to follow cursors; the SDK retains the query filters. GetAutoPagingEnumerable() and GetAutoPagingAsyncEnumerable() load following pages during enumeration and may make several requests. Bound your application work and use cancellation when needed.

An HTTP 202 response still means a pending result. It does not confirm payment or a completed financial effect, and it does not start automatic polling. Read the resource or follow the appropriate event before confirming the result in your application.

Idempotency and errors

The SDK sends Idempotency-Key only when the application supplies it to an endpoint that accepts that header. It does not generate keys or automatically retry POST, PATCH, or DELETE requests. Read retries are optional and default to zero.

Use the HTTP status and ApiErrorException.ErrorCode to decide how to handle a failure. RequestId helps identify the attempt. ErrorMessage is a human explanation and must not be compared as a control code. Do not log complete responses, credentials, personal documents, or temporary links. Review Idempotency and the SDK reference.

Options use Optional<T> to distinguish an omitted field from an explicit value. For updates, omission retains the current value; null clears only fields whose contract allows it. Review each endpoint's conditions.

Use Sandbox

Use a Sandbox key with the simulation services raims.Simulations.Charges and raims.Simulations.Refunds. A Production key does not become a Sandbox key by using these services. Conditions for each simulation are described in the Simulations reference.

Requests that ask for email or webhook delivery can reach external destinations even in Sandbox. Use only destinations authorized for the integration.

Receive webhooks

Read the original body bytes and signing headers received by your server:

using System.Collections.Generic;
using Raims;

var headers = new Dictionary<string, string>
{
    ["webhook-id"] = receivedDeliveryId,
    ["webhook-timestamp"] = receivedTimestamp,
    ["webhook-signature"] = receivedSignature,
};

var webhookEvent = WebhookUtility.ConstructEvent(rawBodyBytes, headers, webhookSecret);

webhookSecret is the secret_key returned when creating or rotating the webhook, not the API Bearer key. Do not reserialize the JSON before verification. A failure throws SignatureVerificationException; do not process the body then.

A valid signature does not prevent duplicate processing. Check type and environment, deduplicate by the event's id, and durably record the work before returning success. The webhook-id header identifies the delivery and does not replace the event identifier. Review Receive events.

Update the SDK

To get the latest stable version from NuGet, run the command again without a version argument:

dotnet add package Raims

NuGet updates the project reference. Review releases and test the flows used by your integration. The SDK version is independent of the API's HTTP /v1 version.

The complete configuration, pagination, error, and webhook guides are available in the SDK repository.