Set up the SDK

The issuer SDK registers payslip records with Verifiabl and makes the QR codes for your payslips. It is available for Node.js, .NET and Ruby. Select the language at the top of the page.

This page gives the requirements, the client and its options. The guide also has these pages:

Retries and timeouts: what the SDK retries and how to set the timeout.
Register payslips: the preparation inputs and the registration results.
Make QR codes: the QR code options.
Handle errors: the errors that the SDK throws and what to do.

For the steps to install the SDK, register payslips and make QR codes, follow Make the QR code in your system.

For each type and member, refer to the Node SDK reference.

For each type and member, refer to the .NET SDK reference.

For each type and member, refer to the Ruby SDK reference.

Requirements

The package requires Node.js 20 or newer.

The package supports .NET 8 or newer, and .NET Framework 4.7.2 or newer.

On .NET Framework, encryption uses the bundled Microsoft.Bcl.Cryptography package. This works on Windows only.

The gem requires Ruby 3.3 or newer. Load it with require "verifiabl/issuer".

Create the client

Create one client. Use it for all calls. The client is thread-safe. It gets an access token and renews it before it expires. For a code example, refer to Authenticate.

If your application uses Microsoft.Extensions.DependencyInjection, add the Verifiabl.Issuer.Extensions.DependencyInjection package. Use the same version as Verifiabl.Issuer. Register the client with AddVerifiablClient. Then inject IVerifiablClient.

using Microsoft.Extensions.DependencyInjection;
using Verifiabl;
using Verifiabl.Client;
using Verifiabl.Extensions.DependencyInjection;

builder.Services.AddVerifiablClient(options =>
{
    options.Environment = VerifiablEnvironment.Sandbox;
    options.Auth = VerifiablAuth.ClientCredentials(clientId, clientSecret);
    options.Timeout = TimeSpan.FromSeconds(120);
});

AddVerifiablClient registers a singleton and gets its HttpClient from IHttpClientFactory. A second call has no effect. The host validates the options at startup.

In a Rails application, create the client in an initializer. The client gets a new access token after a process fork.

Client options

Option	Name	Default
Credentials	`authAuthclient_id:, client_secret:`	Required
Environment	`environmentEnvironmentenvironment:`	Production
Timeout	`timeoutMsTimeouttimeout:`	30 seconds
Retries	`maxRetriesMaxRetriesmax_retries:`	2
HTTP client	`fetchHttpClienttransport:`	Built in
Hooks	`onRequest, onResponse, onErrorOnRequest, OnResponse, OnErroron_request:, on_response:, on_error:`	None
Local issuer URL	`issuerBaseUrlIssuerBaseUrlissuer_base_url:`	None

Credentials are the client ID and the client secret from your onboarding. Keep the client secret in a secrets manager.
Environment is production or sandbox. Use sandbox credentials with the sandbox. Use the same environment when you make the QR code.
Timeout is the maximum time for one method call, in millisecondsa TimeSpanseconds. It includes the token request, all retries and the waits between them. For a pay run batch, set 120 seconds. Refer to Retries and timeouts.
Retries is the number of retries after the first attempt. Set 0 to stop retries.
HTTP client replaces the HTTP layer that the SDK uses. Most integrations do not set it.
Hooks run for each HTTP attempt, retries included. They get the path, and the status, the duration and the request ID of a response. They do not get request or response bodies. If you need help with a request, give the request ID to Verifiabl support.
Local issuer URL is for local development only. Use the environment for sandbox and production.

The SDK uses the global fetch. Set fetch to use a different implementation, for example in tests.

If you set HttpClient, the SDK does not dispose it. Keep its Timeout at the default or set it to Timeout.InfiniteTimeSpan. The dependency injection package sets HttpClient.

Give transport: to Client.new, not to Configuration.new. The built-in transport opens a new connection for each request. For a large pay run, you can give a transport that keeps connections open. Refer to Connection reuse and custom transports.