api-transfer-joesph

ISO 20022 transfer API rail for single-point cash transfer credit messages. Connects to an external API (base URL + API key) and exposes a client and optional HTTP endpoint for core banking applications.

Configuration

Environment variables (see .env.example):

Variable	Description
TRANSFER_RAIL_BASE_URL	External API base URL (e.g. http://187.43.157.150)
TRANSFER_RAIL_API_KEY	API key (e.g. IPv6 or token from provider)
TRANSFER_RAIL_DOCS_PATH	Optional; path to API docs (default: /openapi.json)
TRANSFER_RAIL_API_KEY_HEADER	Optional; header name for API key (default: X-API-Key)
TRANSFER_RAIL_PORT	Optional; port for standalone server (default: 4001)

Do not commit .env. Use a secret manager in production.

Usage

Option A — As a library (in-process)

In the core banking app, add this repo as a submodule (e.g. transfer-rail/) and depend on it:

"dependencies": {
  "api-transfer-joesph": "file:./transfer-rail"
}

Then:

import { createTransferRailClient, getTransferRailConfig } from 'api-transfer-joesph';

const config = getTransferRailConfig();
const client = createTransferRailClient(config);

const result = await client.sendCreditTransfer({
  messageType: 'pacs.008',
  sender: 'SENDERBIC',
  receiver: 'RECEIVERBIC',
  document: { amount: '100', currency: 'USD' },
});

Option B — As an HTTP endpoint (sidecar)

Mount the router in your Express app:

import { createTransferRailRouter } from 'api-transfer-joesph/router';

app.use('/api/transfer-rail', createTransferRailRouter());

Or run the standalone server:

npm run start
# Listens on TRANSFER_RAIL_PORT or 4001

Endpoints:

• GET /api/transfer-rail/health — health check (and optional external API reachability).
• POST /api/transfer-rail/iso20022/send — body: { messageType, sender, receiver, document } (aligned with asle bank API). Returns { success, messageId }.

Fetching API docs from the external host

import { fetchApiDocs, getTransferRailConfig } from 'api-transfer-joesph';

const config = getTransferRailConfig();
const docs = await fetchApiDocs(config);
if (docs.ok && typeof docs.body === 'object') {
  console.log('OpenAPI spec:', docs.body);
}

Adding this repo as a submodule (core banking app)

From the root of the core banking application repo:

git submodule add <repo-url> transfer-rail
git add .gitmodules transfer-rail
git commit -m "Add api-transfer-joesph as transfer-rail submodule"

Clone the parent repo with submodules:

git clone --recurse-submodules <parent-repo-url>
# or after clone:
git submodule update --init --recursive

Update the submodule to latest:

git submodule update --remote transfer-rail

Build and test

npm install
npm run build
npm test

License

ISC