Paymentus Server XOTP Package

XOTP API client for payment functionality

Installation

# Install package
npm install @paymentus/xotp

Usage

Create XotpApiClient

import {
createConfiguration,
ServerConfiguration,
LoggingMiddleware, 
DefaultLogger, 
LogLevel, 
MaskingLevel,
XOTPConfiguration,
XotpApiClient} from "@paymentus/xotp"
import { v4 as uuidv4 } from 'uuid';

const server = new ServerConfiguration<{}>("https://k8-dev.paymentus.io:31443/api", {});

const baseConfig: ConfigurationParameters = {
    authMethods: {
      BearerAuth: {
        tokenProvider: {
          getToken: async () => "valid-jwt"
        }
      },
      "X-Ext-Session-Id": uuidv4(),
      "X-Ext-Session-App": `xotp-sdk@${1.0.0}`
    },
    baseServer: server,
    middleware: [
      new LoggingMiddleware(
        new DefaultLogger(),
        {
          level: LogLevel.NORMAL,
          masking: MaskingLevel.PCI_ONLY
        }
      )
    ]
};

const xotpConfig = createConfiguration({
...baseConfig,
tla: "ABC"
});

const xotp = new XotpApiClient(xotpConfig);

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: '[email protected]',
  dayPhoneNr: 9051112233,
  address: address
};
const paymentPayload: MakePayment = {
  payment: {
    header: [header1, header2],
    paymentMethod: paymentMethod,
    customer: customer
  },
};
const result: MakePaymentResponse = await 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: '[email protected]',
  dayPhoneNr: 9051112233,
  address: address
};
const refundPayload: PaymentRequest = {
  payment: {
    header: header,
    paymentMethod: paymentMethod,
    customer: customer
  },
};
const result: PaymentResponse = await 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 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: '[email protected]',
    dayPhoneNr: 9051112233
}
const stagePaymentPayload: PaymentRequest = {
  payment: {
    header: header,
    customer: customer
  }
}
const result: StagePaymentResponse = await 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 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 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: '[email protected]',
  dayPhoneNr: 9051112233
}
const autopayPayload: AutopayRequest = {
  paymentSchedule: {
    header: header,
    paymentMethod: paymentMethod,
    customer: customer,
    paymentMethodCategory: PaymentMethodCategoryEnum.Cc
  },
}
const result: AutopayResponse = await xotp.createAutopay(autopayPayload);


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

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

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

const searchPayload:AutopaySearchRequest = {
  loginId: "[email protected]",
  accountNumber: "6759372"
}
const result: AutopayListResponse = await 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 xotp.updateAutopay(referenceNumber, autopayPayload);


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

const result: AutopayResponse = await 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: '[email protected]',
    dayPhoneNr: 9051112233
}
const stageAutopayPayload: PaymentRequest = {
    payment: {
        header: header,
        customer: customer,
        paymentMethodCategory: PaymentMethodCategoryEnum.Cc
    }
}
const result: StagePaymentResponse = await 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 xotp.accountInquiry(payload);


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

let result: ListAccountInfoResponse = await xotp.getAccountInfoByEmail("[email protected]");

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

const accountNumber = "6759370"
const result: ListAccountInfoResponse = await 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: "[email protected]"
}

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

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


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

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


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

const loginId = "[email protected]";
const result: ListProfilesResponse = await 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 xotp.updateProfile("FE2EF495A1152561572949784C16BF23ABB28057",
payload)


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

const profileToken = "12C6FC06C99A462375EEB3F43DFD832B08CA9E17";
const result: ProfileResponse = await 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: "[email protected]"
}
const userInfo: UserInfo = {
  loginId: "[email protected]",
  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 xotp.createUser(userCreatePayload);

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

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

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

let result: UserFindResponse = await xotp.getUser("[email protected]");

// 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: "[email protected]",
    profile: profile
}
const userWithPermission: UserLoginId = {
    loginId: "[email protected]"    
}
const userProfile: UserUpdateRequestItem = {
    userInfo: userInfo,
    user: userWithPermission
}
const userCreatePayload: UserUpdateRequest = {
    userProfile: userProfile
}
const userResponse: UserResponse = await 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: '[email protected]'
}
const payment: ResendEmailRequestItem = {
    header: header,
    customer: customer
}
let resendRequest: ResendEmailRequest = {
    payment: payment
}
const result: ResendEmailResponse = await xotp.resendEmailConfirmation(resendRequest);


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

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

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/.

License

MIT