Dot0.Jibit
10.1.2
dotnet add package Dot0.Jibit --version 10.1.2
NuGet\Install-Package Dot0.Jibit -Version 10.1.2
<PackageReference Include="Dot0.Jibit" Version="10.1.2" />
<PackageVersion Include="Dot0.Jibit" Version="10.1.2" />
<PackageReference Include="Dot0.Jibit" />
paket add Dot0.Jibit --version 10.1.2
#r "nuget: Dot0.Jibit, 10.1.2"
#:package Dot0.Jibit@10.1.2
#addin nuget:?package=Dot0.Jibit&version=10.1.2
#tool nuget:?package=Dot0.Jibit&version=10.1.2
Dot0.Jibit
The library contains independent clients for Transferor (group settlement) and Identicator (IDE inquiries). Each service has its own folder, namespace, credentials, token cache, and response/error models.
Transferor: group settlements
Dot0.Jibit.Transferor.JibitTransferorClient implements the supplied Transferor REST API v2.5 specification.
The default service root is https://napi.jibit.ir/trf/; all operations use /v2/ beneath it.
Jibit must activate Transferor for your account and allowlist your outgoing IP addresses.
Use Transferor credentials, not IDE tokens. The library has no dependency on an application or storage system.
Submit and track a settlement
using Dot0.Jibit.Transferor;
// Reuse HttpClient and one Transferor client per account across requests.
// The application owns HttpClient and configures its timeout and handlers.
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
var transferor = new JibitTransferorClient(http, apiKey, secretKey);
// Create these IDs once for a NEW settlement. Persist the complete batch BEFORE sending.
// After a timeout, load the original IDs and inquire; do not generate new IDs and resubmit.
var batch = new JibitBatchRequest
{
BatchId = Guid.NewGuid().ToString("N"),
SubmissionMode = JibitSubmissionModes.Batch,
Transfers =
[
new JibitTransferRequest
{
TransferId = Guid.NewGuid().ToString("N"),
Destination = recipientIban, // A valid IR-prefixed IBAN supplied by your application.
Amount = 1_000_000, // One million rials, NOT one million tomans.
Currency = JibitTransferCurrencies.Irr,
TransferMode = JibitTransferModes.Ach,
Description = "Settlement",
Cancellable = true // Hold for one hour before sending to the bank.
}
]
};
// Persist batch here using your application's storage.
var accepted = await transferor.SubmitBatchAsync(batch);
Console.WriteLine($"Accepted: {accepted.SubmittedCount}; rejected: {accepted.Rejections.Length}");
// Acceptance is not bank settlement. Query again later while the result is pending.
var inquiry = await transferor.GetTransfersAsync(batchId: batch.BatchId);
foreach (var item in inquiry.Transfers)
Console.WriteLine($"{item.TransferId}: {item.State}; reason: {item.FailReason}");
BATCH means accept the whole batch or none. This describes acceptance, not atomic settlement by banks.
TRANSFER means consider items in their input order while settleable funds suffice; some can be rejected
even when the HTTP response succeeds. Always inspect SubmittedCount and Rejections.
Payments use the settleable wallet; GetBalancesAsync returns both main and settleable balances.
Amount is a positive long in the requested currency: IRR and RIALS mean rials; TOMAN means tomans.
The client never converts amounts. TotalAmountTransferred in the submission result is always in rials,
and fees use their own FeeCurrency (documented as IRR). Do not add values in different currencies directly.
ACH is Paya, NORMAL is an intrabank transfer, and RTGS is Satna. Omitting TransferMode uses ACH.
The server enforces current bank and amount rules. GetSupportedNormalBanksAsync returns supported banks,
while GetActiveNormalBanksAsync returns currently active banks. Both return SWIFT codes such as MELIIR,
not IDE bank identifiers such as MELLI. Availability may change before submission.
Optional recipient names are resolved from the IBAN when omitted. PaymentId is the bank payment identifier
(شناسه واریز), not your tracking TransferId. Metadata is a string; serialize any application JSON yourself.
NotifyUrl receives Jibit POST notifications with inquiry-style transfer information. The specification does
not define callback authentication, retries, or a separate callback envelope; use inquiries for reconciliation.
Identifiers and IBANs remain strings so leading zeros are preserved.
Cancellation, retry, receipts, and generation
// Methods taking selectors require batchId, transferId, or both.
var payment = await transferor.GetTransfersAsync(transferId: savedTransferId);
await transferor.CancelTransfersAsync(transferId: savedTransferId);
// Explicitly retry a failed payment only after inspecting its failure reason.
await transferor.RetryTransfersAsync(transferId: failedTransferId);
// Anyone holding this enabled link can view the receipt. It expires after one hour by default.
var receipt = await transferor.SetReceiptEnabledAsync(true, batchId: savedBatchId);
await transferor.SetReceiptEnabledAsync(false, batchId: savedBatchId);
// Generate and inspect instructions without submitting any payment.
var generated = await transferor.GenerateBatchAsync(new JibitBatchGenerationRequest
{
Destination = recipientIban,
Amount = 200_000_000,
Currency = JibitTransferCurrencies.Toman,
TransferMode = JibitTransferModes.Ach,
Description = "Settlement"
});
// Inspect and persist generated before explicitly calling SubmitBatchAsync(generated).
Omitting Cancellable uses the service default of true: transfers are held for one hour before bank submission.
Setting it to false removes that hold. Only eligible cancellable transfers can be cancelled.
Cancellation and retry requests return no typed body; inquire afterward to confirm the result.
CANCELLING, INITIALIZED, and IN_PROGRESS are pending states. The other documented states are
CANCELLED, TRANSFERRED, FAILED, and MANUALLY_FAILED. See JibitTransferStates for constants.
States remain strings so new service states can still be read.
The batch generator only prepares instructions. The v2.5 document describes splitting amounts above
100 million tomans; Jibit determines the actual generated batch. It does not execute the batch automatically.
Receipt duration is an account setting that Jibit support can change. The client sends receipt enablement
as the string "true" or "false", matching the documented field type.
Filtering and daily reports
var filtered = await transferor.FilterTransfersAsync(new JibitTransferFilter
{
State = JibitTransferStates.Transferred, // Omit to include all states.
From = DateTimeOffset.UtcNow.AddDays(-1),
To = DateTimeOffset.UtcNow,
Page = 1, // One-based.
Size = 100 // 1 through 250.
});
Console.WriteLine(filtered.GetRawText());
// Persian calendar yyMMdd; preserve leading zeros. 000708 means 1400/07/08.
var report = await transferor.GetDailyReportAsync("000708");
The specification does not describe the filter response envelope. FilterTransfersAsync therefore returns
the complete JsonElement, including any pagination metadata, without guessing a schema.
Use FilterTransfersAsync<YourResponseModel> once you know your account's actual response shape.
The client requests exactly one page; it does not automatically fetch every page.
Filter timestamps are converted to UTC ISO 8601, matching the document's examples. Inquiry timestamps accept
both ISO 8601 and RFC 1123 (the format named by the document) and expose UTC DateTimeOffset? values.
Unknown fields in typed service responses are retained in AdditionalData.
Authentication, errors, and uncertain outcomes
Authentication and renewal happen on demand, with one authentication request at a time per client.
Transferor access tokens last 24 hours and refresh tokens last 48 hours; the cache uses a one-minute
safety margin for each. If the refresh token has expired, the client generates a new pair using the credentials.
GenerateTokenAsync and RefreshTokenAsync are also available explicitly. Failed refreshes propagate to the caller.
Read-only ApiKey and SecretKey properties expose the original constructor credentials; these keys do not
rotate during authentication. The token and expiration properties always reflect the latest successful automatic
or explicit generation/refresh:
await transferor.RefreshTokenAsync();
var apiKey = transferor.ApiKey;
var secretKey = transferor.SecretKey;
var accessToken = transferor.AccessToken;
var accessExpiryUtc = transferor.AccessTokenExpireDate;
var refreshToken = transferor.RefreshToken;
var refreshExpiryUtc = transferor.RefreshTokenExpireDate;
You can persist AccessToken, AccessTokenExpireDate, RefreshToken, and RefreshTokenExpireDate
and pass them to the matching optional constructor parameters when restoring a client. Expiration properties
are UTC DateTime? cache deadlines. Local inputs are converted to UTC; unspecified inputs are treated as UTC.
Unlike newly generated tokens, saved tokens have an unknown age: without a saved access expiration, the client
renews before use; without a saved refresh expiration it generates a new pair. It never assumes an old token
has a fresh 24/48-hour lifetime. Keep credentials and saved tokens in secure application storage.
All operations accept a CancellationToken. The caller's HTTP timeout is respected. An optional HTTPS
baseAddress overrides the supplied HTTP client's base address and then the default; include the service
path (normally /trf/), not an endpoint or /v2/. The client does not mutate shared HTTP default headers.
try
{
var status = await transferor.GetTransfersAsync(transferId: savedTransferId);
}
catch (JibitTransferorException ex)
{
Console.WriteLine($"HTTP {ex.StatusCode}; support fingerprint: {ex.Fingerprint}");
foreach (var error in ex.Errors)
Console.WriteLine($"{error.Code}: {error.Message}");
}
Unsuccessful HTTP responses throw JibitTransferorException, preserving StatusCode, all Errors,
Fingerprint, and the original ResponseBody, including non-JSON gateway errors. Use error codes for
programmatic decisions. Diagnostics can contain personal/payment information; handle logs accordingly.
Timeouts, cancellation, and transport errors propagate as the underlying exceptions. They do not prove
that a payment was rejected. Inquire with the persisted identifiers before deciding how to recover.
The client never automatically replays requests, including after 401/403; configure external handlers accordingly.
Service rejection codes include transfer.already_exists, balances.not_enough, cancellation.not_applicable,
and retry.not_applicable. Indexed codes such as transfers.0.destination.not_valid identify an invalid item.
Offline Transferor tests require no credentials and never call Jibit:
dotnet test Test/Test.csproj --filter FullyQualifiedName~JibitTransferorClientTests
Identicator (IDE): inquiries
Identity lookup by national code and Persian birth date is available through:
var identity = await jibit.GetIdentityAsync("0123456789", "13700101", completeInfo: true);
Console.WriteLine(identity.IdentityInfo?.FirstName);
completeInfo defaults to false. Accounts configured for complete identity records always receive them.
Fields omitted from partial records remain null. Authentication and request tracking use the client defaults.
To run the identity live test, set JIBIT_NATIONAL_CODE, JIBIT_BIRTH_DATE (Persian yyyyMMdd),
and optionally JIBIT_COMPLETE_INFO=true, then run:
dotnet test Test/Test.csproj --filter 'FullyQualifiedName=Dot0.Test.Jibit.JibitIdeTest.GetIdentity' --logger 'console;verbosity=detailed'
HTTP client for Jibit's Identicator (استعلام) API, based on the supplied Persian technical document v1.5.2.
The inquiry API lives in the Ide folder and Dot0.Jibit.Ide namespace. All response and nested model types use the Jibit prefix.
The default API base address is https://napi.jibit.ir/ide/.
using Dot0.Jibit.Ide;
// Reuse HttpClient and JibitClient in your application.
using var http = new HttpClient();
var jibit = new JibitClient(http, apiKey, secretKey);
var result = await jibit.MatchMobileToNationalCodeAsync("0123456789", "09123456789");
Console.WriteLine(result.Matched);
var card = await jibit.GetCardAsync("1234123412341234");
Console.WriteLine(card.CardInfo?.OwnerName);
Authentication is automatic. The client renews access tokens on the next request once 25 minutes have elapsed.
Refresh tokens are cached for 48 hours with a one-minute safety margin. Token acquisition is serialized for concurrent calls.
GenerateTokenAsync and RefreshTokenAsync are also available explicitly. The caller owns the supplied
HttpClient; its timeout and handler configuration are respected. Cancellation tokens are supported.
An optional HTTPS base address can override the default.
Saved tokens can be supplied when creating a client:
var jibit = new JibitIdeClient(http, apiKey, secretKey,
accessToken: savedAccessToken,
accessTokenExpireDate: savedAccessExpiryUtc,
refreshToken: savedRefreshToken,
refreshTokenExpireDate: savedRefreshExpiryUtc);
// Read these after an inquiry or explicit token generation/refresh to persist the current values.
var accessToken = jibit.AccessToken;
var accessExpiryUtc = jibit.AccessTokenExpireDate;
var refreshToken = jibit.RefreshToken;
var refreshExpiryUtc = jibit.RefreshTokenExpireDate;
All four constructor parameters are optional and nullable. Expiry parameters and properties use
DateTime?; returned dates always have Kind = DateTimeKind.Utc. Local inputs are converted to UTC,
and unspecified inputs are treated as UTC. Token and expiry properties are null when the corresponding
token is unavailable. Omitted expiries use the cache durations above, starting at client creation.
Expired saved access tokens are refreshed if the saved refresh token is still valid; otherwise a new pair is generated.
The client supports card/IBAN inquiries, card-to-account and card/account-to-IBAN conversion,
card-to-IBAN availability, ownership matching by national code or name, Shahkar, postal address and coordinates,
identity similarity, foreigner and corporation identity, military qualification, Sana registration,
balances, and daily usage reports. Responses are typed and retain unknown JSON fields in AdditionalData.
Identifiers stay strings to preserve leading zeros. Birth dates use the Persian calendar in yyyyMMdd;
daily report dates use Persian yyMMdd (for example 000708). Bank identifiers use the uppercase names
from Jibit's bank table, such as MELLI or MELLAT. Identity similarity needs at least one name.
Unsuccessful responses throw JibitException, exposing StatusCode, Code, Message, ResponseBody,
and TrackId for support. Each request has an X-TRACK-ID. The client does not retry failed inquiries
automatically. A forbidden response can indicate invalid authentication or an inactive account; inspect
the response and account configuration before explicitly generating a new token.
Run the tests
From the repository root, run the offline tests:
dotnet test Test/Test.csproj --filter FullyQualifiedName~JibitClientTests
For real API calls, set credentials in the shell where you run tests:
$env:JIBIT_API_KEY = '<your API key>'
$env:JIBIT_SECRET_KEY = '<your secret key>'
dotnet test Test/Test.csproj --filter 'FullyQualifiedName~JibitLiveTests.GenerateToken' --logger 'console;verbosity=detailed'
Set the inputs for the inquiry you want to exercise, then select its test:
$env:JIBIT_NATIONAL_CODE = '<10-digit national code>'
$env:JIBIT_MOBILE_NUMBER = '<mobile number>'
dotnet test Test/Test.csproj --filter 'FullyQualifiedName~JibitLiveTests.Shahkar' --logger 'console;verbosity=detailed'
| Test | Additional environment variables |
|---|---|
| GenerateToken, RefreshToken, Balances | None |
| CardInquiry, CardToIban | JIBIT_CARD_NUMBER |
| IbanInquiry | JIBIT_IBAN |
| Shahkar | JIBIT_NATIONAL_CODE, JIBIT_MOBILE_NUMBER |
| PostalAddress | JIBIT_POSTAL_CODE |
Missing inputs mark live tests inconclusive/skipped. To run all configured live tests, use
--filter TestCategory=JibitLive. Successful inquiries may incur Jibit charges. Your account must have the
requested service enabled and your outgoing IP must be allowlisted by Jibit. Results are printed to test
output, including inquiry data; token values are omitted. A matching result of false is a valid API response.
The Test project excludes the old BaleBotTest.cs and TelegramBotTest.cs samples because they reference
the removed Dot0.TelegramMvc API. Their source files are preserved.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.