Translite Web Service SDK

React Native `0.73.2` SDK for the Translite processor-core ISO8583 webservice APIs. API Reference
- Calls processor-core wrapped APIs.
- Initializes a terminal with `terminalId` and `serialNumber`.
- Stores the backend-provisioned `combinedKey`.
- Can perform one-call terminal bootstrap through the backend.
- Also supports individual key exchange requests:
  - `9A`: master key
  - `9B`: session key
  - `9G`: PIN key
  - `9C`: terminal parameters
- Decrypts master, session, and PIN keys.
- Parses field `62` terminal parameters into meaningful JSON.
- Builds payment and reversal requests for `/api/v1/iso8583/process`.

API Reference

Creating a Client

npm install translite-web-service-sdk

Then install package dependencies:

yarn install

Npm Url link

https://www.npmjs.com/package/translite-web-service-sdk

Backend Endpoints Used

Initialize Terminal

POST {baseUrl}/api/v1/terminals/initialize

Request:

{
  "terminalId": "2KUD0001",
  "serialNumber": "TERM-SERIAL-001"
}

Wrapped response:

{
  "status": "success",
  "responseCode": "00",
  "failureReason": null,
  "data": {
    "terminalId": "2KUD0001",
    "serialNumber": "TERM-SERIAL-001",
    "combinedKey": "0123456789ABCDEFFEDCBA9876543210"
  }
}

ISO8583 Processing

POST {baseUrl}/api/v1/iso8583/process

The SDK unwraps the backend response and returns the data payload.

The SDK exposes two ways to call this endpoint:

• processPayment(...) and reverseTransaction(...) for normal financial flows.
• processIso8583(...) for callers that need to send the exact backend ISO8583 request payload.

Terminal Bootstrap

POST {baseUrl}/api/v1/terminals/bootstrap

This endpoint performs 9A, 9B, 9G, and 9C on the backend and returns encrypted keys plus parsed terminal parameters in one response.

Basic Usage

The entry point into the SDK is the TransliteWebServiceClient.

import {
    TransliteWebServiceClient,
    MemoryTerminalStore
} from "translite-web-service-sdk";

const client = new TransliteWebServiceClient({
    baseUrl: "https://payment.translite.africa",
    storage: new MemoryTerminalStore()
});

Configuration

interface TransliteWebServiceClientOptions {
    baseUrl: string;
    storage: TerminalStore;
    headersProvider?: () => Promise<Record<string, string>>
        | Record<string, string>;
}

| Property | Type | Required | Description | | ----------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- | | baseUrl | string | ✅ | Base URL of the Processor-Core backend. | | storage | TerminalStore | ✅ | Storage implementation used to persist terminal information and cryptographic keys. | | headersProvider | () => Promise<Record<string, string>> or () => Record<string, string> | No | Supplies additional HTTP headers such as authentication tokens. |

Terminal Initialization

Registers a terminal with the backend and stores the returned Combined Key.

await client.initialize(
    terminalId,
    serialNumber
);

Parameters

| Name | Type | Description | | -------------- | -------- | ----------------------- | | terminalId | string | Terminal Identifier. | | serialNumber | string | Terminal Serial Number. |

Returns

Promise<InitializeTerminalResponse>

interface InitializeTerminalResponse {
    terminalId: string;
    serialNumber: string;
    combinedKey: string;

    masterKey?: string;
    masterKeyKcv?: string;

    sessionKey?: string;
    sessionKeyKcv?: string;

    pinKey?: string;
    pinKeyKcv?: string;

    parameters?: TerminalParameters;

    lastInitializedAt?: string;
    lastKeyExchangeAt?: string;
}

processPayment and reverseTransaction also accept the optional fields supported by processor-core, including transmissionDateTime, localTransactionTime, localTransactionDate, cardSequenceNumber, posPinCaptureCode, transactionFee, acquiringInstitutionId, track2Data, serviceRestrictionCode, securityControlInfo, echoData, paymentInformation, field62, posDataCode, primaryMessageHash, and secondaryMessageHash.

Raw ISO8583 Example

Use processIso8583 when the mobile app already has a full ISO8583 web request shape and should not go through the payment helper defaults:

const response = await client.processIso8583({
  mti: '0200',
  pan: '5061082005145118086',
  processingCode: '000000',
  amount: '000000005000',
  transmissionDateTime: '0705123456',
  stan: '123456',
  localTransactionTime: '123456',
  localTransactionDate: '0705',
  expirationDate: '2806',
  merchantType: '5999',
  posEntryMode: '051',
  posConditionCode: '00',
  rrn: '123456789012',
  terminalId: '2KUD0001',
  merchantId: 'MERCHANT1234567',
  merchantNameLocation: 'TEST MERCHANT LAGOS NG',
  currencyCode: '566',
  iccData: '9F2608...',
});

Error Handling

Terminal Bootstrap

Performs the complete key exchange using a single backend request.

await client.bootstrapTerminal(
    terminalId,
    serialNumber
);

The backend performs:

• 9A – Master Key
• 9B – Session Key
• 9G – PIN Key
• 9C – Terminal Parameters

The SDK decrypts the keys, validates them, stores them securely, and returns the result.

Parameters

| Name | Type | | -------------- | -------- | | terminalId | string | | serialNumber | string |

Returns

Promise<TerminalBootstrapResponse>

interface TerminalBootstrapResponse {
    terminalId: string;

    masterKeyKcv: string;
    sessionKeyKcv: string;
    pinKeyKcv: string;

    parameters: TerminalParameters;

    rawResponses: {
        masterKey: Iso8583ResponseData;
        sessionKey: Iso8583ResponseData;
        pinKey: Iso8583ResponseData;
        parameters: Iso8583ResponseData;
    };
}

Full Key Exchange

Executes the traditional key exchange flow.

await client.performFullKeyExchange(
    terminalId
);

Sequence:

1. Download Master Key (9A)
2. Download Session Key (9B)
3. Download PIN Key (9G)
4. Download Terminal Parameters (9C)

Parameters

| Name | Type | | ------------ | -------- | | terminalId | string |

Returns

Promise<TerminalBootstrapResponse>

Process Payment

Processes an ISO8583 purchase transaction.

const response = await client.processPayment(request);

Parameters

interface ProcessPaymentRequest {
    terminalId: string;
    pan: string;
    amount: number;
    expiry: string;

    rrn: string;

    iccData?: string;

    posEntryMode: string;

    posConditionCode: string;

    merchantId: string;

    merchantNameLocation: string;
}

Returns

Promise<Iso8583ResponseData>

Process Reversal

Processes a financial reversal.

const response = await client.processReversal(request);

Returns

Promise<Iso8583ResponseData>

ISO8583 Response

Every ISO8583 transaction returns the same object.

export interface Iso8583ResponseData {
    mti: string | null;
    transactionId: string | null;
    processor: string | null;
    responseCode: string | null;
    responseDescription: string | null;
    authorizationCode: string | null;
    rrn: string | null;
    stan: string | null;
    terminalId: string | null;
    fields: Record<string, string>;
}

Field Descriptions

| Property | Description | | --------------------- | ------------------------------------------------------- | | mti | ISO8583 Message Type Indicator. | | transactionId | Backend-generated transaction identifier. | | processor | Processor that handled the request. | | responseCode | ISO8583 response code (00 indicates success). | | responseDescription | Human-readable response message. | | authorizationCode | Authorization code returned by the processor. | | rrn | Retrieval Reference Number. | | stan | System Trace Audit Number. | | terminalId | Terminal Identifier. | | fields | Map of ISO8583 data elements returned by the processor. |

Example:

{
    "39": "00",
    "37": "123456789012",
    "38": "A12345",
    "55": "9F2608..."
}

Terminal Parameters

The SDK parses ISO8583 Field 62 into a strongly typed object.

export interface TerminalParameters {
    epmsDateTime: string;
    cardAcceptorIdCode: string;
    hostTimeOut: string;
    currencyCode: string;
    countryCode: string;
    callHomeTime: string;
    merchantCategoryCode: string;
    merchantNameLocation: string;
    merchantNameLocationTrimmed: string;
    rawField62: string;
}

Storage

Applications must provide a storage implementation.

interface TerminalStore {
    save(state: TerminalState): Promise<void>;

    load(): Promise<TerminalState | null>;

    clear(): Promise<void>;
}

The SDK ships with:

MemoryTerminalStore

which is intended only for development and testing.

Error Handling

The SDK throws two error types.

TransliteApiError

Returned when the backend responds with an error.

try {
    await client.processPayment(request);
} catch (error) {
    if (error instanceof TransliteApiError) {
        console.log(error.code);
        console.log(error.message);
    }
}

TransliteSdkError

Returned when the SDK encounters local errors such as:

• invalid input
• missing terminal initialization
• missing keys
• decryption failure
• validation errors
• storage errors

try {
    await client.performFullKeyExchange("2KUD0001");
} catch (error) {
    if (error instanceof TransliteSdkError) {
        console.log(error.code);
        console.log(error.details);
    }
}