Delphi SDK

The Delphi SDK connects a backend to the Raims public API through source units with typed services, parameters, and responses. The distribution is source code to compile on your application's target. Check the platform requirements when setting up the installation. Do not embed API keys in distributed desktop or mobile binaries.

The SDK reference lists each resource's methods and parameters.

Install the SDK

Download source from the current GitHub release and preserve the complete src directory. The base source requires Delphi 10.4; some targets require later versions. Check the platform requirements and use an edition that includes your compiler and required native SDKs.

In the IDE, open Project, Options, and Delphi Compiler. Add the src location to the project's Search path for each target and configuration you use. For global configuration, the Delphi Library options let you add it to the selected platform's Library path. The IDE library documentation explains this selection. Keep compiled files in your application's output directory, separate from the source.

Use Raims.Client, Raims.Core, Raims.Params, and Raims.Models; add Raims.Webhooks for events. The SDK uses the standard System.JSON and System.Net.HttpClient libraries without a UI framework. Examples are Delphi procedure snippets; also import System.SysUtils and System.JSON.

Configure the client

Obtain a credential through API keys and keep it in your backend. Company, environment, and permissions come from the validated key. Sandbox and Production use https://api.raims.com.

uses
  System.SysUtils, Raims.Client, Raims.Core, Raims.Models;

var
  Client: TRaimsClient;
  Options: TRaimsClientOptions;
begin
  Options := TRaimsClientOptions.Default;
  Options.TimeoutMilliseconds := 80000;
  Options.MaxNetworkRetries := 0;
  Client := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_API_KEY'), Options);
  try
    // Use Client here.
  finally
    Client.Free;
  end;
end;

Initialize options through Default. Timeouts use milliseconds and apply to native transport phases rather than a total operation deadline. Calls are synchronous; visual applications should run network work outside the UI thread. The next snippets use an open Client. It owns its services; your application frees the client, parameters, and returned resources using try/finally.

Create a customer and a charge

CustomerTaxId is the authorized customer's valid CPF or CNPJ. CustomerKey and ChargeKey are separate strings persisted before sending. DueDateUnix is an Int64 due date in UTC Unix seconds; RequestId is an application string. The types below are in Raims.Params, Raims.Models, and Raims.Core.

var
  CustomerParams: TCreateCustomerParams;
  ChargeParams: TCreateChargeParams;
  Customer: TCustomerCreated;
  Charge: TChargeCreated;
  RequestOptions: TRaimsRequestOptions;
  CustomerId: string;
begin
  CustomerParams := TCreateCustomerParams.Create;
  try
    CustomerParams.SetTaxId(CustomerTaxId);
    RequestOptions := TRaimsRequestOptions.Default;
    RequestOptions.IdempotencyKey := CustomerKey;
    Customer := Client.Customers.Create(CustomerParams, RequestOptions);
    try
      CustomerId := Customer.Id;
    finally
      Customer.Free;
    end;
  finally
    CustomerParams.Free;
  end;

  ChargeParams := TCreateChargeParams.Create;
  try
    ChargeParams.SetCustomerId(CustomerId).SetAmountCents(15000);
    ChargeParams.SetDueDate(DueDateUnix).SetTitle('Order 1234');
    RequestOptions := TRaimsRequestOptions.Default;
    RequestOptions.IdempotencyKey := ChargeKey;
    Charge := Client.Charges.Create(ChargeParams, RequestOptions);
    try
      RequestId := Charge.LastResponse.RequestId;
    finally
      Charge.Free;
    end;
  finally
    ChargeParams.Free;
  end;
end;

15000 represents BRL 150.00. Not calling a setter leaves a field absent; SetExternalReferenceNull on TUpdateCustomerParams sends null where the contract permits clearing that reference. UnsetExternalReference removes the input field. In responses, HasField and IsNull distinguish presence and null before interpreting a getter that returns zero or an empty string.

Pagination and pending results

List customers and visit up to one hundred items:

var
  Page: TCustomerListResponse;
begin
  Page := Client.Customers.List;
  try
    Page.AutoPagingEach(
      procedure(CustomerJson: TJSONObject)
      begin
        ProcessCustomer(CustomerJson);
      end,
      100);
  finally
    Page.Free;
  end;
end;

ProcessCustomer is your handler. The callback receives a borrowed TJSONObject: do not free or mutate it, and copy it before retaining it after the callback. AutoPagingEach frees additional pages; your application frees the first one. NextPage and PreviousPage return new pages or nil; the caller owns those pages. Filters and options are preserved.

HTTP 202 accepts an operation with a pending result. Retrieve the resource or follow its webhook before confirming a financial effect. Preserve LastResponse.StatusCode and RequestId to identify the attempt.

Idempotency and errors

var
  Current: TCustomerListItem;
begin
  try
    Current := Client.Customers.Retrieve(CustomerId);
    try
      RequestId := Current.LastResponse.RequestId;
    finally
      Current.Free;
    end;
  except
    on E: ERaimsApiError do
      HandleApiFailure(E.LastResponse.StatusCode, E.Code, E.LastResponse.RequestId);
    on E: ERaimsConnectionError do
      HandleConnectionFailure;
  end;
end;

The handlers belong to your application. ERaimsApiError exposes Code, ErrorType, ApiMessage, and LastResponse; ERaimsConnectionError represents transport failures. Log only necessary metadata without credentials or full bodies. If you access ApiError, retain and free the returned copy.

The SDK does not generate keys or retry writes automatically. After a lost response, reconcile the operation and keep its key and parameters if the endpoint permits another attempt. MaxNetworkRetries enables eligible read retries only; the default is zero. Retry-After follows the SDK's bounded wait policy. See Idempotency.

Use Sandbox

Use a Sandbox key and a charge created in that environment:

var
  SandboxClient: TRaimsClient;
  Simulation: TChargeSimulation;
begin
  SandboxClient := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_SANDBOX_API_KEY'));
  try
    Simulation := SandboxClient.Simulations.Charges.ConfirmPayment(SandboxChargeId);
    try
      RequestId := Simulation.LastResponse.RequestId;
    finally
      Simulation.Free;
    end;
  finally
    SandboxClient.Free;
  end;
end;

SandboxChargeId and RequestId are application strings. The key determines the environment; the SDK does not change it through headers or operating system selection. Financial simulations require Sandbox. See Simulations. Email requests and webhooks may reach external destinations; use authorized ones.

Receive webhooks

Preserve RawBody as the original TBytes received by your server. Set WebhookSecret to the webhook's secret_key; the three Received... values come from the original headers. Before building the array below, reject duplicate signing-header occurrences instead of choosing one of them.

var
  Headers: TArray<TRaimsHeader>;
  Event: TJSONObject;
begin
  SetLength(Headers, 3);
  Headers[0] := TRaimsHeader.Create('webhook-id', ReceivedDeliveryId);
  Headers[1] := TRaimsHeader.Create('webhook-timestamp', ReceivedTimestamp);
  Headers[2] := TRaimsHeader.Create('webhook-signature', ReceivedSignature);
  Event := TRaimsWebhook.ConstructEvent(RawBody, Headers, WebhookSecret);
  try
    PersistEvent(Event);
  finally
    Event.Free;
  end;
end;

The types are in System.JSON, Raims.Core, and Raims.Webhooks. PersistEvent is your handler and the caller owns Event. ERaimsSignatureError identifies verification failure: do not process the event in that case. Do not reserialize the body before verification. The default tolerance is 300 seconds; keep the server clock synchronized.

After verification, check type and environment, deduplicate the event id, and store the work durably before returning success. webhook-id identifies the delivery. See Receive events.

Update the SDK

Review release notes and replace all units with source from the same revision. Preserve the selected Search path or Library path, remove old compiled units from your application's output, and rebuild every target in use. Do not mix a new unit with the rest of an older version. Check your integration with its compiler, operating system, and configuration before making the application available.