soutrapay-bank-middleware

Angular bank middleware SDK for SoutraPay — embed a complete checkout experience for wallet top-ups and settlements directly in your host application.

The middleware presents payment options (linked banks and payment gateways), handles secure authorization (transaction PIN / OTP), runs the payment flow against your configured API, and returns a clear success, failure, or pending result to your app.

Table of contents

• Features
• Requirements
• Installation
• What the middleware does
• Quick start
• Configuration
• Inputs & outputs
• Result object
• Optional auth provider
• Localization
• License

Features

• Drop-in Angular checkout component (<soutrapay-bank-middleware>)
• Top-up and settlement flows
• Bank account and payment-gateway selection UI
• Secure authorization (transaction PIN / OTP)
• Host-controlled amount, charges, branding, and language
• onComplete / onClose events for host handling
• Optional DI-based auth token provider
• Bundled English labels with host override support

Requirements

| Package | Version | |---------|---------| | @angular/core | ^20.3.0 | | @angular/common | ^20.3.0 | | @angular/forms | ^20.3.0 | | @angular/animations | ^20.3.0 | | rxjs | ^7.8.0 |

Installation

npm install soutrapay-bank-middleware

What the middleware does

Once you mount the component with a valid config, the SDK:

1. Shows a branded checkout shell (amount, user, company)
2. Loads available payment types (bank / gateway)
3. For bank types, lists the user’s linked accounts and lets them pick one
4. Collects authorization when required (PIN or OTP)
5. Completes the payment with your backend using the configured endpoint and headers
6. Displays processing and final status screens
7. Emits onComplete with the outcome, or onClose if the user dismisses checkout

Your host app is responsible for opening/closing the UI and reacting to the result (toasts, navigation, receipts, etc.).

Quick start

1. Import the component

import { Component } from '@angular/core';
import {
  CheckoutShellComponent,
  SoutraPayConfig,
  SoutraPayResult,
  SoutraPayChargeLine,
} from 'soutrapay-bank-middleware';

@Component({
  selector: 'app-checkout',
  standalone: true,
  imports: [CheckoutShellComponent],
  templateUrl: './checkout.component.html',
})
export class CheckoutPageComponent {
  showCheckout = false;

  config: SoutraPayConfig = {
    type: 'TOPUP', // or 'SETTLEMENT'
    amount: 100,
    currency: 'USD',
    companyName: 'Your Company',
    user: {
      name: 'Jane Doe',
      phone: '+1 555 0100',
      avatarText: 'JD',
      // avatarUrl: 'https://cdn.example.com/avatar.jpg', // optional
    },
    userProfile: {
      firstName: 'Jane',
      lastName: 'Doe',
      phoneNumber: '5550100',
      dialCode: '+1',
      userType: 1,
      accountId: 'ACCOUNT_ID',
    },
    javaEndpoint: 'https://api.example.com/v1',
    userId: 'USER_ID',
    companyId: 'COMPANY_ID',
    walletId: 'WALLET_ID',
    defaultHeaders: {
      Authorization: 'Bearer <access-token>',
    },
    // Optional: host LABEL_* map for translated UI
    // languageDictionary: { LABEL_PAY_SECURELY: 'Pay securely', ... },
  };

  charges: SoutraPayChargeLine[] = [
    { label: 'Service fee', amount: 1.5 },
  ];
  payableAmount = 101.5;

  openCheckout(): void {
    this.showCheckout = true;
  }

  onComplete(result: SoutraPayResult): void {
    // Handle SUCCESS | FAILED | PENDING
    console.log(result.status, result.transactionId, result.statusCode);
    this.showCheckout = false;
  }

  onClose(): void {
    this.showCheckout = false;
  }
}

2. Render the middleware

<button type="button" (click)="openCheckout()">Pay</button>

@if (showCheckout) {
  <soutrapay-bank-middleware
    [config]="config"
    [charges]="charges"
    [payableAmount]="payableAmount"
    (onComplete)="onComplete($event)"
    (onClose)="onClose()">
  </soutrapay-bank-middleware>
}

3. Settlement example

Use the same component; only change the flow type and party info as needed:

const settlementConfig: SoutraPayConfig = {
  ...this.config,
  type: 'SETTLEMENT',
  // debitUserInfo / creditUserInfo as required by your integration
};

Configuration

Pass a SoutraPayConfig object via [config].

| Field | Type | Required | Description | |-------|------|----------|-------------| | type | 'TOPUP' \| 'SETTLEMENT' | Yes | Checkout flow | | amount | number | Yes | Transaction amount | | currency | string | Yes | Currency code (e.g. USD) | | user | SoutraPayUser | Yes | Display name, phone, initials / image | | javaEndpoint | string | Yes* | API base URL used by the middleware | | userId | string | Yes* | Authenticated user id | | companyId | string | Recommended | Company / tenant id | | companyName | string | No | Brand name in the UI | | walletId | string | No | Wallet reference | | userProfile | SoutraPayUserProfile | Recommended | Profile used for auth / payment | | debitUserInfo | SoutraPayPartyInfo | Flow-dependent | Debit party | | creditUserInfo | SoutraPayPartyInfo | Flow-dependent | Credit party | | defaultHeaders | Record<string, string> | Recommended | Auth and other API headers | | languageDictionary | Record<string, string> | No | Host LABEL_* overrides | | agentChargesInfo | object \| null | No | Pre-calculated charges from host | | taxInfo | object \| null | No | Tax breakdown from host |

*Required for the middleware to load payment options and complete payments.

User object

interface SoutraPayUser {
  name: string;
  phone: string;
  avatarText: string;   // shown when no image
  avatarUrl?: string;   // optional profile image
}

Inputs & outputs

Inputs

| Input | Type | Description | |-------|------|-------------| | config | SoutraPayConfig | Required checkout configuration | | charges | SoutraPayChargeLine[] | Optional charge lines shown in summary | | payableAmount | number \| null | Optional total payable (amount + charges) |

Outputs

| Output | Payload | When | |--------|---------|------| | onComplete | SoutraPayResult | Payment finished (success, failure, or pending) | | onClose | — | User closes / cancels the checkout |

Result object

interface SoutraPayResult {
  status: 'SUCCESS' | 'FAILED' | 'PENDING';
  /** 1 Pending · 2 Approved · 3 Success · 4 Failed · 5 Rejected */
  statusCode?: number | null;
  type: 'TOPUP' | 'SETTLEMENT';
  transactionId: string;
  txnNumber?: string;
  amount: number;
  currency: string;
  reason?: string;
  provider?: string;
}

Example handling:

onComplete(result: SoutraPayResult): void {
  switch (result.status) {
    case 'SUCCESS':
      // Show receipt / refresh balance
      break;
    case 'FAILED':
      // Show result.reason or a generic failure message
      break;
    case 'PENDING':
      // Inform the user that confirmation is still in progress
      break;
  }
  this.showCheckout = false;
}

Optional auth provider

You can supply tokens via Angular DI instead of (or in addition to) defaultHeaders:

import { Provider } from '@angular/core';
import {
  SOUTRAPAY_AUTH_PROVIDER,
  SoutraPayAuthProvider,
} from 'soutrapay-bank-middleware';

export const soutraPayAuthProvider: Provider = {
  provide: SOUTRAPAY_AUTH_PROVIDER,
  useValue: {
    getToken: () => sessionStorage.getItem('access_token'),
    getCompanyId: () => sessionStorage.getItem('company_id'),
    getUserId: () => sessionStorage.getItem('user_id'),
  } satisfies SoutraPayAuthProvider,
};

Register soutraPayAuthProvider in your application providers.

Localization

The middleware ships with English labels. To use your app’s language map, pass matching LABEL_* keys:

config: SoutraPayConfig = {
  // ...
  languageDictionary: {
    LABEL_PAY_SECURELY: 'Pay securely',
    LABEL_PAYMENT_FAILED: 'Payment failed',
    LABEL_TRY_ANOTHER_BANK: 'Try another bank',
    LABEL_CANCEL_PAYMENT: 'Cancel payment',
    LABEL_FLOW_TOPUP: 'Top-up',
    LABEL_FLOW_SETTLEMENT: 'Settlement',
    LABEL_TRANSACTION_PIN: 'Transaction PIN',
    // ...other LABEL_* keys used by the checkout UI
  },
};

Host dictionary values override the bundled defaults.

License

MIT © SoutraMoney