@paymentus/core

Paymentus Server SDK

A modular Node.js SDK for Paymentus API services, providing a unified interface for authentication and API access.

Features

• Modular Architecture: Use individual packages or the unified SDK
• TypeScript Support: Full type safety and IntelliSense
• Automatic Token Management: Seamless JWT token handling (via @paymentus/auth)
• Error Handling: Comprehensive error types and messages
• Configuration Validation: Runtime validation of configuration options
• Granular Scope Support: Targeted API access via granular access scopes
• Pixel Integration: Automatic scope mapping for Paymentus pixels
• XOTP Integration: Full support for payment API functionality

Packages

• @paymentus/auth - Authentication API client for JWT token management
• @paymentus/xotp - XOTP API client for payment functionality
• @paymentus/core - Unified SDK package that includes all modules

Installation

We recommend installing the core package that includes all modules, but you can install the individual packages if you only need a specific module.

# Install individual packages
npm install @paymentus/auth
npm install @paymentus/xotp

# Or install the core package that includes all modules
npm install @paymentus/core

Usage

Using Individual Packages

import { Auth } from '@paymentus/auth';
import { XOTP } from '@paymentus/xotp';

// Initialize auth client with multiple scopes
const authClient = new Auth({
  baseUrl: 'https://api.paymentus.com',
  preSharedKey: 'your-pre-shared-key',
  scope: ['xotp'], // Base scopes
  tla: 'TST',
  aud: 'WEB_SDK', // Optional audience
  pixels: ['tokenization-pixel', 'list-wallets-pixel'] // Automatically adds required scopes
});

// Fetch token
const token = await authClient.fetchToken();

// Initialize XOTP client with token
const xotpClient = new XOTP({
  baseUrl: 'https://api.paymentus.com',
  authToken: token
});

let payload: AccountInquiryRequest = {
  accountNumber: '6759370',
  paymentTypeCode: 'UTILITY',
  authToken1: '12345',
  includeSchedules: true,
  includeLastUsedPm: true,
  detailedInfo: true
}
let result: AccountInquiryResponse = await xotpClient.accountInquiry(payload);

Using the Unified SDK

import { SDK } from '@paymentus/core';
import { LogLevel, MaskingLevel } from '@paymentus/core';


// Initialize the SDK with configuration
const sdk = new SDK({
  baseUrl: 'https://api.paymentus.com',
  preSharedKey: 'your-pre-shared-key',
  tla: 'TST',
  aud: 'WEB_SDK',
  // Auth options
  auth: {
    scope: ['xotp'],
    userLogin: '[e-mail]',
    pmToken: ['token1', 'token2'],
    paymentsData: [{
      accountNumber: '123456',
      convFeeState: 'NY',
      convFeeCountry: 'US'
    }]
  },
  // Logging options
  logging: {
    level: LogLevel.NORMAL,
    masking: MaskingLevel.PCI_ONLY
  },
  // Session options
  session: {
    id: 'custom-session-id'
  }
});

Payment Examples

// Example 1: Make Payment
import {
    Address, Customer, MakePayment,
    PaymentHeader, PaymentMethod,
    MakePaymentResponse,
    PaymentOperationTypeEnum,
    PaymentMethodTypeEnum
} from '@paymentus/xotp';

const header1: PaymentHeader = {
  operation: PaymentOperationTypeEnum.Sale,
  accountNumber: '6759373',
  paymentAmount: 13.21,
  paymentTypeCode: 'UTILITY'
};
const header2: PaymentHeader = {
  operation: PaymentOperationTypeEnum.Sale,
  accountNumber: '6759370',
  paymentAmount: 20.00,
  paymentTypeCode: 'WATER'
};
const paymentMethod: PaymentMethod = {
  type: PaymentMethodTypeEnum.Visa,
  accountNumber: '4111111111111111',
  cardHolderName: 'John Doe',
  creditCardExpiryDate: {
    month: 12,
    year: 2035
  }
};
const address: Address = {
  line1: '10 Fifth Ave.',
  state: 'NY',
  zipCode: '12345',
  city: 'New York',
  country: 'US'
};
const customer: Customer = {
  firstName: 'John',
  lastName: 'Doe',
  email: '[e-mail]',
  dayPhoneNr: 9051112233,
  address: address
};
const paymentPayload: MakePayment = {
  payment: {
    header: [header1, header2],
    paymentMethod: paymentMethod,
    customer: customer
  },
};
const result: MakePaymentResponse = await sdk.xotp.makePayment(paymentPayload);


// Example 2: Refund Payment
import {
  Address, Customer,
  PaymentHeader, PaymentMethod,
  PaymentMethodTypeEnum,
  PaymentRequest,
  PaymentResponse
} from '@paymentus/xotp';

const header: PaymentHeader = {
  accountNumber: '6759370',
  paymentAmount: 10,
  paymentTypeCode: 'UTILITY'
};
const paymentMethod: PaymentMethod = {
  type: PaymentMethodTypeEnum.VisaIrefund,
  accountNumber: '4111111111111111',
  cardHolderName: 'Guest Pay',
  creditCardExpiryDate: {
    month: 12,
    year: 2035
  }
};
const address: Address = {
  line1: '10 Fifth Ave.',
  state: 'NY',
  zipCode: '12345',
  city: 'New York',
  country: 'US'
};
const customer: Customer = {
  firstName: 'John',
  lastName: 'Doe',
  email: '[e-mail]',
  dayPhoneNr: 9051112233,
  address: address
};
const refundPayload: PaymentRequest = {
  payment: {
    header: header,
    paymentMethod: paymentMethod,
    customer: customer
  },
};
const result: PaymentResponse = await sdk.xotp.refundPayment(refundPayload);


// Example 3: Fetch Last Payment
import { PaymentSearchRequest, PaymentSearchResponse } from '@paymentus/xotp';

const payload: PaymentSearchRequest = {
  accountNumber: '6759370',
  paymentTypeCode: 'UTILITY'
};
const result: PaymentSearchResponse = await sdk.xotp.fetchLastPayment(payload);


// Example 4: Stage Payment
import {
  StagePaymentResponse,
  PaymentHeader,
  Customer,
  PaymentRequest
} from '@paymentus/xotp';

const header: PaymentHeader = {
    accountNumber: '6759374',
    paymentAmount: 13.21,
    paymentTypeCode: 'UTILITY',
    authToken1: '12345'
}
const customer: Customer = {
    firstName: 'John',
    lastName: 'Doe',
    email: '[e-mail]',
    dayPhoneNr: 9051112233
}
const stagePaymentPayload: PaymentRequest = {
  payment: {
    header: header,
    customer: customer
  }
}
const result: StagePaymentResponse = await sdk.xotp.stagePayment(stagePaymentPayload);


// Example 5: Convenience Fee Calculation
import {
    PaymentMethod, PaymentMethodTypeEnum,
    PaymentHeader,
    PaymentMethodCategoryEnum,
    ConvenienceFeeCountryEnum,
    PaymentResponse,
    PaymentRequest
} from '@paymentus/xotp';

const header: PaymentHeader = {
    operation: PaymentOperationTypeEnum.ConvFee,
    paymentAmount: 25.00,
    convenienceFeeCountry: ConvenienceFeeCountryEnum.Us
}
const paymentMethod: PaymentMethod = {
    type: PaymentMethodTypeEnum.Visa
}
const feePayload: PaymentRequest = {
    payment: {
      header: header,
      paymentMethod: paymentMethod,
      paymentMethodCategory: PaymentMethodCategoryEnum.Cc
    }
}
const result: PaymentResponse = await sdk.xotp.cnvCalculation(feePayload);


// Example 6: Payment History
import { PaymentHistoryResponse, PaymentSearchRequest } from '@paymentus/xotp';

const accountNumber = '6759375';
const paymentTypeCode = 'UTILITY';
const authToken1 = '12345';
// Optional date range (format: MMDDYYYY)
const dateFrom = '01012023';
const dateTo = '12312025';

const payload: PaymentSearchRequest = {
  'account-number': accountNumber,
  'payment-type-code': paymentTypeCode,
  'auth-token1': authToken1,
  'date-from': dateFrom,
  'date-to': dateTo
};
const result: PaymentHistoryResponse = await sdk.xotp.getPaymentHistory(payload);

Autopay Examples

// Example 1: Create autopay
import {
  AutopayRequest,
  AutopayResponse,
  Customer,
  PaymentHeader,
  PaymentMethod,
  PaymentMethodCategoryEnum,
  ScheduleTypeCodeEnum
} from '@paymentus/xotp';

const header: PaymentHeader = {
    accountNumber: "6759371",
    paymentTypeCode: "WATER",
    scheduleTypeCode: ScheduleTypeCodeEnum.Monthly,
    scheduleDay: 24,
    paymentAmount: 15.00
}
const paymentMethod: PaymentMethod = {
  token: "827BFC458708F0B442009C9C9836F7E4B65557FB"
}
const customer: Customer = {
  firstName: 'John',
  lastName: 'Doe',
  email: '[e-mail]',
  dayPhoneNr: 9051112233
}
const autopayPayload: AutopayRequest = {
  paymentSchedule: {
    header: header,
    paymentMethod: paymentMethod,
    customer: customer,
    paymentMethodCategory: PaymentMethodCategoryEnum.Cc
  },
}
const result: AutopayResponse = await sdk.xotp.createAutopay(autopayPayload);


// Example 2: Get Autopay
import { AutopayFindResponse } from '@paymentus/xotp';

const referenceNumber = "3445"
const result: AutopayFindResponse = await sdk.xotp.getAutopay(referenceNumber);

// Example 3: List Autopay
import { AutopayListResponse, AutopaySearchRequest } from '@paymentus/xotp';

const searchPayload:AutopaySearchRequest = {
  loginId: "[e-mail]",
  accountNumber: "6759372"
}
const result: AutopayListResponse = await sdk.xotp.listAutoPay(searchPayload);

// Example 4: Update Autopay
import {
  AutopayRequest, AutopayResponse,
  PaymentHeader
} from '@paymentus/xotp'

// Reference Number of autopay to update 
const referenceNumber = "3445"
const header: PaymentHeader = {
      scheduleDay: 14,
      paymentAmount: 20.00
}
const autopayPayload: AutopayRequest = {
    paymentSchedule: {
      header: header
    }
}
const result: AutopayResponse = await sdk.xotp.updateAutopay(referenceNumber, autopayPayload);


// Example 5: Delete Autopay
import { AutopayResponse } from '@paymentus/xotp';

const result: AutopayResponse = await sdk.xotp.deleteAutopay("3454");


//Example 6: Stage Autopay
import {
  Customer,
  PaymentHeader,
  PaymentMethodCategoryEnum,
  ScheduleTypeCodeEnum,
  PaymentRequest,
  StagePaymentResponse
} from '@paymentus/xotp';

const header: PaymentHeader = {
    accountNumber: '6759374',
    paymentAmount: 13.21,
    paymentTypeCode: 'UTILITY',
    scheduleTypeCode: ScheduleTypeCodeEnum.Monthly,
    authToken1: '12345',
    scheduleStartDate: "08152025",
    scheduleDay: 15
}
const customer: Customer = {
    firstName: 'John',
    lastName: 'Doe',
    email: '[e-mail]',
    dayPhoneNr: 9051112233
}
const stageAutopayPayload: PaymentRequest = {
    payment: {
        header: header,
        customer: customer,
        paymentMethodCategory: PaymentMethodCategoryEnum.Cc
    }
}
const result: StagePaymentResponse = await sdk.xotp.stageAutopay(stageAutopayPayload);

Accounts Examples

// Example 1: Accounts Inquiry
import { AccountInquiryRequest, AccountInquiryResponse } from '@paymentus/xotp';

let payload: AccountInquiryRequest = {
    accountNumber: '6759370',
    paymentTypeCode: 'UTILITY',
    authToken1: '12345',
    includeSchedules: true,
    includeLastUsedPm: true,
    detailedInfo: true
}
let result: AccountInquiryResponse = await sdk.xotp.accountInquiry(payload);


// Example 2: AccountInfo by email
import { ListAccountInfoResponse } from '@paymentus/xotp';

let result: ListAccountInfoResponse = await sdk.xotp.getAccountInfoByEmail("[e-mail]");

// Example 3: AccountInfo by account number
import { ListAccountInfoResponse } from '@paymentus/xotp';

const accountNumber = "6759370"
const result: ListAccountInfoResponse = await sdk.xotp.getAccountInfoByAccountNumber(accountNumber);

Profile Examples

// Example 1: Create Profile
import {
  ProfileCustomer,
  ProfilePaymentMethod,
  PaymentMethodTypeEnum,
  ProfileRequest,
  ProfileResponse,
  ProfileUserInfo
} from '@paymentus/xotp';

const paymentMethod: ProfilePaymentMethod = {
    type: PaymentMethodTypeEnum.Visa,
    accountNumber: '4444444444444448',
    creditCardExpiryDate: {
        month: 12,
        year: 2035
    },
    cardHolderName: 'John Doe'
}

const userInfo: ProfileUserInfo = {
    loginId: "[e-mail]"
}

const customer: ProfileCustomer = {
    firstName: "John",
    lastName: "Doe",
}

const payload: ProfileRequest = {
    profile: {
        paymentMethod: paymentMethod,
        customer: customer,
        userInfo: userInfo
    }
}
const result: ProfileResponse = await sdk.xotp.createProfile(payload)


// Example 2: Get Profile
import { ProfileResponse } from '@paymentus/xotp';

const profileToken = "12C6FC06C99A462375EEB3F43DFD832B08CA9E17";
const result: ProfileResponse = await sdk.xotp.getProfile(profileToken);


// Example 3: List Profiles
import { ListProfilesResponse } from '@paymentus/xotp';

const loginId = "[e-mail]";
const result: ListProfilesResponse = await sdk.xotp.getProfiles(loginId);


// Example 4: Update Profile
import {
  ProfileResponse,
  ProfileUpdateRequest
} from '@paymentus/xotp';

const profileToken = "12C6FC06C99A462375EEB3F43DFD832B08CA9E17";

const payload: ProfileUpdateRequest = {
    profile: {
        profileDescription: "John Doe Default Payment Profile",
        defaultFlag: true
    }
}
const result: ProfileResponse = await sdk.xotp.updateProfile("FE2EF495A1152561572949784C16BF23ABB28057",
payload)


// Example 5: Delete Profile
import { ProfileResponse } from '@paymentus/xotp';

const profileToken = "12C6FC06C99A462375EEB3F43DFD832B08CA9E17";
const result: ProfileResponse = await sdk.xotp.deleteProfile(profileToken);

User Examples

// Example 1: Create User
import {
ClientAccountItem,
UserInfo, UserProfileInfo, UserRequest,
UserRequestItem,
UserResponse
} from '@paymentus/xotp';

const profile: UserProfileInfo = {
  firstName: "John",
  lastName: "Doe",
  email: "[e-mail]"
}
const userInfo: UserInfo = {
  loginId: "[e-mail]",
  password: "SecretPassword123",
  forcePasswordChange: true,
  profile: profile
}
const clientAccount: ClientAccountItem = {
  accountNumber: "6759372",
  paymentTypeCode: "UTILITY",
  authToken1: "12345"
}
const userProfile: UserRequestItem = {
  userInfo: userInfo,
  clientAccount: [clientAccount]
}
const userCreatePayload: UserRequest = {
  userProfile: userProfile
}
const result: UserResponse = await sdk.xotp.createUser(userCreatePayload);

// Example 2: Delete User
import {  UserResponse, UserLoginId, UserDeleteRequest  } from '@paymentus/xotp';

const userWithPermission: UserLoginId = {
  loginId: "[e-mail]"
}
const deleteUserRequest: UserDeleteRequest = {  
  userProfile: {
      user: userWithPermission,
      userInfo: {
          loginId: "[e-mail]"
      }
  }
}
let result:UserResponse  = await sdk.xotp.deleteUser(deleteUserRequest);

// Example 3: Get User
import { UserFindResponse } from '@paymentus/xotp';

let result: UserFindResponse = await sdk.xotp.getUser("[e-mail]");

// Example 4: Update User
import {
    ClientAccountItem,
    UserInfo,
    UserProfileInfo,
    UserUpdateRequest,
    UserUpdateRequestItem,
    UserLoginId,
    UserResponse
} from '@paymentus/xotp';

const profile: UserProfileInfo = {
    dayPhoneNr: "1234567890",
    zipCode: "12345"
}
const userInfo: UserInfo = {
    loginId: "[e-mail]",
    profile: profile
}
const userWithPermission: UserLoginId = {
    loginId: "[e-mail]"    
}
const userProfile: UserUpdateRequestItem = {
    userInfo: userInfo,
    user: userWithPermission
}
const userCreatePayload: UserUpdateRequest = {
    userProfile: userProfile
}
const userResponse: UserResponse = await sdk.xotp.updateUser(userCreatePayload);

Other Examples

// Example 1: Resend Email Confirmation
import {
  Customer,
  ResendEmailRequest,
  ResendEmailRequestHeader,
  ResendEmailRequestItem,
  ResendEmailResponse
} from '@paymentus/xotp';

const header: ResendEmailRequestHeader = {
    accountNumber: '6759370',
    referenceNumber: '731358'
}
const customer: Customer = {
    email: '[e-mail]'
}
const payment: ResendEmailRequestItem = {
    header: header,
    customer: customer
}
let resendRequest: ResendEmailRequest = {
    payment: payment
}
const result: ResendEmailResponse = await sdk.xotp.resendEmailConfirmation(resendRequest);


// Example 2: Bank Info
import { BankInfoResponse } from '@paymentus/xotp';

const routingNumber = "021000128"
const result: BankInfoResponse = await sdk.xotp.getBankInfo(routingNumber);

Custom Logging Middleware

You can implement custom logging middleware by creating a class that implements the Logger interface. Here's an example:

import { Logger, LogLevel, MaskingLevel, LoggingMiddleware } from '@paymentus/core';

// Custom logger implementation
class CustomLogger implements Logger {
  log(level: LogLevel, message: string, data?: any): void {
    // Implement your custom logging logic here
    switch (level) {
      case LogLevel.DEBUG:
        console.debug(`[DEBUG] ${message}`, data);
        break;
      case LogLevel.NORMAL:
        console.log(`[INFO] ${message}`, data);
        break;
      case LogLevel.ERROR:
        console.error(`[ERROR] ${message}`, data);
        break;
    }
  }
}

// Initialize SDK with custom logger
const sdk = new SDK({
  baseUrl: 'https://developer.paymentus.io',
  preSharedKey: 'your-pre-shared-key',
  tla: 'TST',
  auth: {
    scope: ['xotp']
  },
  logging: {
    level: LogLevel.NORMAL,
    masking: MaskingLevel.PCI_ONLY,
    logger: new CustomLogger()
  }
});

// Example: Using custom logger with XOTP client
try {
  const accountInfo = await sdk.xotp.accountInquiry('123456', 'UTILITY', '12345');
  // Custom logger will automatically log the request and response
} catch (error) {
  // Custom logger will automatically log any errors
  console.error('Error:', error);
}

Available Log Levels

The SDK supports the following log levels to control the verbosity of logging output:

SILENT

Suppresses all logging output. Use this in production environments where you want to minimize overhead and don't need operational visibility.

const sdk = new SDK({
  // ... other configuration
  logging: {
    level: LogLevel.SILENT,
    masking: MaskingLevel.PCI_ONLY
  }
});

MINIMAL

Logs only essential information such as request initiation and completion status with response codes. Use this for basic operational monitoring with minimal verbosity.

const sdk = new SDK({
  // ... other configuration
  logging: {
    level: LogLevel.MINIMAL,
    masking: MaskingLevel.PCI_ONLY
  }
});

NORMAL

The default log level. Logs request/response information including basic request bodies and error details. Suitable for most development and staging environments.

const sdk = new SDK({
  // ... other configuration
  logging: {
    level: LogLevel.NORMAL,
    masking: MaskingLevel.PCI_ONLY
  }
});

VERBOSE

Maximum logging level that includes all request/response details, headers, and timing information. Ideal for debugging integration issues in development environments.

const sdk = new SDK({
  // ... other configuration
  logging: {
    level: LogLevel.VERBOSE,
    masking: MaskingLevel.ALL_PII
  }
});

Available Masking Levels

The SDK also supports data masking to protect sensitive information in logs:

• NONE: No data masking is applied. Only use in secure environments where logs are properly protected.
• PCI_ONLY: Masks payment card information (account numbers, CVV) while preserving other data for debugging.
• ALL_PII: Maximum protection that masks all personally identifiable information including names, addresses, and payment data.

Combining Log Levels with Custom Loggers

You can combine log levels with a custom logger implementation for advanced logging scenarios:

import { LogLevel, MaskingLevel, Logger } from '@paymentus/core';

// Custom logger implementation
class CustomLogger implements Logger {
  info(message: string, ...args: any[]): void {
    // Send logs to your monitoring system
    myMonitoringSystem.log('INFO', message, ...args);
  }

  error(message: string, ...args: any[]): void {
    // Alert on errors
    myMonitoringSystem.alert('ERROR', message, ...args);
  }

  warn(message: string, ...args: any[]): void {
    myMonitoringSystem.log('WARN', message, ...args);
  }

  debug(message: string, ...args: any[]): void {
    myMonitoringSystem.log('DEBUG', message, ...args);
  }
}

const sdk = new SDK({
  // ... other configuration
  logging: {
    level: LogLevel.NORMAL,
    masking: MaskingLevel.PCI_ONLY,
    logger: new CustomLogger()
  }
});

Advanced Configuration Examples

Example 1: Multiple Payment Methods

const sdk = new SDK({
  baseUrl: 'https://api.paymentus.com',
  preSharedKey: 'your-pre-shared-key',
  tla: 'TST',
  auth: {
    scope: ['xotp'],
    pmToken: ['token1', 'token2'],
    paymentsData: [
      {
        accountNumber: '123456',
        convFeeState: 'NY',
        convFeeCountry: 'US'
      },
      {
        accountNumber: '789012',
        convFeeState: 'CA',
        convFeeCountry: 'US'
      }
    ]
  }
});

Example 2: Debug Logging with PCI Masking

const sdk = new SDK({
  baseUrl: 'https://api.paymentus.com',
  preSharedKey: 'your-pre-shared-key',
  tla: 'TST',
  auth: {
    scope: ['xotp']
  },
  logging: {
    level: LogLevel.DEBUG,
    masking: MaskingLevel.PCI_ONLY
  }
});

Configuration Options

Global Configuration

• baseUrl (required): API base URL
• preSharedKey (required): Your pre-shared key
• tla (required): Three-letter account identifier
• aud (optional): Audience identifier (e.g., 'WEB_SDK')

Auth Options

• scope (optional): Array of API scopes
• userLogin (optional): User login identifier
• pmToken (optional): Array of payment method tokens
• paymentsData (optional): Array of payment data objects

Logging Options

• level (optional): Log level (NORMAL, DEBUG, etc.)
• masking (optional): Masking level for sensitive data
• logger (optional): Custom logger implementation

Session Options

• id (optional): Custom session ID (UUID generated if not provided)

XOTP API Methods

The SDK provides comprehensive access to the XOTP API through the sdk.xotp client. Here are the available methods:

Account Management

• accountInquiry(accountNumber, paymentTypeCode, authToken1?, authToken2?, authToken3?, accountToken?, includeSchedules?, includeLastUsedPm?, detailedInfo?): Get account information
• fetchLastPayment(accountNumber, paymentTypeCode?, authToken1?, authToken2?, authToken3?, accountToken?): Search for last payment

Profile Management

• createProfile(createProfileRequest): Create a new profile
• getProfile(token): Get profile by ID
• getProfiles(loginId, paymentMethodTypes?): View wallet entries
• updateProfile(token, updateProfileRequest?): Update a wallet entry
• deleteProfile(token): Delete a wallet entry

Autopay Management

• createAutopay(createAutopayRequest): Create an autopay
• getAutopay(referenceNumber, detailedInfo?): Get autopay details
• updateAutopay(referenceNumber, updateAutopayRequest): Update an autopay
• deleteAutopay(referenceNumber): Delete an autopay
• listAutoPay(loginId, accountNumber, paymentTypeCode?, authToken1?, authToken2?, authToken3?, searchInactive?, detailedInfo?, api?): List autopay entries

Payment Processing

• makePayment(makePaymentRequest?): Process a payment
• cnvCalculation(convenienceFeeCalculate): Calculate convenience fee
• getBTClientToken(getBTClientTokenRequest): Create XML client token

Bank Information

• getBankInfo(routingNumber): Retrieve bank information

const sdk = new SDK({
  baseUrl: 'https://api.paymentus.com',
  preSharedKey: 'your-pre-shared-key',
  tla: 'TST',
  auth: {
    scope: ['xotp'],
    pmToken: ['token1', 'token2'],
    aud: 'WEB_SDK'
  }
});

const token = await sdk.auth.fetchToken();

const paymentResult = await sdk.xotp.makePayment({
    "payment": {
      "header": [{
        "account-number": "6759370",
        "account-token": "123",
        "auth-token1": "12345",
        "payment-amount": 20.55,
        "payment-type-code": "UTILITY",
        "check-duplicates": false
      }],
      "payment-method": {
        "token": "ABSDFSDFSDFSDF",
      },
      "customer": {
        "first-name": "John",
        "middle-name": "V",
        "last-name": "Doe",
        "day-phone-nr": 9051112233,
        "email": "[e-mail]",
        "address": {
          "line1": "10 Fifth Ave.",
          "line2": "string",
          "state": "NY",
          "city": "New York",
          "country": "US"
        }
      },
      "external-data":{
        "test": "test"
      }
    }
  })

  console.log(paymentResult);

Available Scopes

The SDK supports the following scopes:

• xotp - Basic XOTP functionality
• xotp:profile - Profile management
• xotp:profile:read - Read profile data
• xotp:profile:create - Create profiles
• xotp:profile:update - Update profiles
• xotp:profile:delete - Delete profiles
• xotp:listProfiles - List profiles
• xotp:payment - Payment processing
• xotp:autopay - Autopay functionality
• xotp:autopay:delete - Delete autopay settings
• xotp:accounts - Account management
• xotp:accounts:listAccounts - List accounts

Pixel Integration

The SDK provides automatic scope mapping for Paymentus pixels. When you specify pixels in the configuration, the SDK automatically adds the required scopes and validates required claims:

const sdk = new SDK({
  baseUrl: 'https://secure1.paymentus.com',
  preSharedKey: 'your-pre-shared-key',
  tla: 'ABC',
  auth: {
    scope: ['xotp'],
    // Required claims for user-checkout-pixel:
    userLogin: '[e-mail]',
    paymentsData: [{
      accountNumber: '123456',
      convFeeState: 'NY',
      convFeeCountry: 'US'
    }]
  }
});

Available pixels and their requirements:

• tokenization-pixel:

  • Scopes: ['xotp:profile']
  • Claims: None required

• list-wallets-pixel:

  • Scopes: ['xotp:profile', 'xotp:listProfiles']
  • Claims: userLogin required

• user-checkout-pixel:

  • Scopes: ['xotp:profile', 'xotp:payment', 'xotp:listProfiles', 'xotp:accounts:listAccounts']
  • Claims: userLogin and paymentsData required, pmTokens optional

• guest-checkout-pixel:

  • Scopes: ['xotp:payment', 'xotp:accounts:listAccounts']
  • Claims: paymentsData required

• user-autopay-pixel:

  • Scopes: ['xotp:profile', 'xotp:autopay', 'xotp:listProfiles', 'xotp:accounts:listAccounts']
  • Claims: userLogin and paymentsData required, pmTokens optional

Error Handling

The SDK provides specific error types for different scenarios:

• ConfigurationError: Invalid configuration (e.g., empty scope array)
• TokenError: Token validation or authentication failures
• NetworkError: API request failures
• ApiError: API-specific errors

Example error handling:

try {
  await sdk.auth.fetchToken();
} catch (error) {
  if (error instanceof ConfigurationError) {
    console.error('Invalid configuration:', error.message);
  } else if (error instanceof TokenError) {
    console.error('Token error:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof ApiError) {
    console.error('API error:', error.message);
  }
}

Disclaimer

These SDKs are intended for use with the URLs and keys that are provided to you for your company by Paymentus. If you do not have this information, please reach out to your implementation or account manager. If you are interested in learning more about the solutions that Paymentus provides, you can visit our website at paymentus.com. You can request access to our complete documentation at developer.paymentus.io. If you are currently not a customer or partner and would like to learn more about the solution and how you can get started with Paymentus, please contact us at https://www.paymentus.com/lets-talk/.

Contact us

If you have any questions or need assistance, please contact us at [e-mail].

License

MIT