Node.js Sample

A comprehensive Node.js implementation of the PIPA PayCenter API client that demonstrates all available API operations including Credit Transfers, Payment Requests, and routing eligibility checks.

🚀 Quick Start

Prerequisites

• Node.js 16.x or higher
• npm or yarn package manager
• PIPA PayCenter API credentials (Client ID, Client Secret, Institution ID)

Installation

1. Install dependencies:

cd NodeJSSample
npm install

2. Configure your credentials:

cp .env.example .env

3. Edit .env and add your actual credentials:

PIPA_CLIENT_ID=your_client_id_here
PIPA_CLIENT_SECRET=your_client_secret_here
PIPA_INSTITUTION_ID=your_institution_id_here

4. Run the demo:

npm start

📁 Project Structure

NodeJSSample/
├── index.js                    # Main demo application
├── PIPAPayCenterClient.js      # API client implementation
├── config.js                   # Configuration management
├── package.json                # Dependencies and scripts
├── .env.example                # Environment variables template
├── .gitignore                  # Git ignore rules
├── README.md                   # Documentation
└── payloads/                   # Sample JSON payloads
    ├── credit-transfer.json
    ├── payment-request.json
    ├── payment-request-response.json
    └── credit-transfer-response-to-payment-request.json

🔑 Configuration

The application uses environment variables for configuration. Copy .env.example to .env and configure:

Variable	Required	Description	Default
PIPA_BASE_URL	No	API base URL	https://ipa01.eagle.jhapaycenter.com
PIPA_CLIENT_ID	Yes	OAuth2 Client ID	-
PIPA_CLIENT_SECRET	Yes	OAuth2 Client Secret	-
PIPA_INSTITUTION_ID	Yes	Your Institution ID	-
PIPA_ENVIRONMENT	No	Environment	sandbox
LOCAL_ACCOUNT_NAME	No	Local account name	PC-Tester
LOCAL_ACCOUNT_NUMBER	No	Local account number	556677
LOCAL_ACCOUNT_TYPE	No	Local account type	Checking
REMOTE_ACCOUNT_NAME	No	Remote account name	PC-Test
REMOTE_ACCOUNT_NUMBER	No	Remote account number	201990001
REMOTE_ACCOUNT_ROUTING	No	Remote routing number	711060274

📖 API Operations Implemented

The client implements all 11 operations from the OpenAPI specification:

1. Authentication

await client.authenticate();

Obtains an OAuth2 Bearer token using client credentials.

2. Create Credit Transfer

const response = await client.createCreditTransfer(creditTransferPayload, xRequestId);

Posts a new credit transfer to send funds from a local account to a remote account.

3. Get Credit Transfer by X-Request-ID

const transfer = await client.getCreditTransferByRequestId(xRequestId);

Retrieves a credit transfer using the idempotency key.

4. Get Credit Transfer by Track ID

const transfer = await client.getCreditTransferByTrackId(trackId);

Retrieves a credit transfer using the PayCenter tracking identifier.

5. Check Routing Number Eligibility

const eligibility = await client.checkRoutingEligibility(routingNumber);

Checks if a routing number is eligible for PIPA transactions.

6. Create Payment Request (RfP)

const response = await client.createPaymentRequest(paymentRequestPayload, xRequestId);

Creates a new Request for Payment (RfP) to request funds from a remote account.

7. Update Payment Request Status

const response = await client.updatePaymentRequestStatus(trackId, statusUpdate);

Accepts or rejects a payment request.

8. Get Payment Request by X-Request-ID

const request = await client.getPaymentRequestByRequestId(xRequestId);

Retrieves a payment request using the idempotency key.

9. Get Payment Request by Track ID

const request = await client.getPaymentRequestByTrackId(trackId);

Retrieves a payment request using the PayCenter tracking identifier.

10. Create Credit Transfer for Payment Request

This uses the same createCreditTransfer method but includes the PaymentRequestDetails section:

const payload = {
  CreditTransfer: {
    // ... standard fields
    PaymentRequestDetails: {
      RfPPmtHubTrakId: "payment-request-track-id"
    }
  }
};
await client.createCreditTransfer(payload);

🎯 Usage Examples

Run All Demos

npm start

This runs all demos in sequence:

1. Credit Transfer - Direct money transfer
2. Routing Eligibility - Check if routing number supports PIPA
3. Credit Transfer for Payment Request - Respond to an accepted RfP (shows info message)
4. Complete Payment Request Workflow - Create → Accept → Pay

Run Specific Demo

npm start credit-transfer          # Direct credit transfer demo
npm start routing                  # Routing eligibility check
npm start credit-transfer-rfp      # Credit transfer for RfP (info only)
npm start payment-request          # Full RfP workflow

Use in Your Own Code

import PIPAPayCenterClient from './PIPAPayCenterClient.js';

const client = new PIPAPayCenterClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  institutionId: 'your_institution_id',
  environment: 'sandbox'
});

// Authenticate
await client.authenticate();

// Create a credit transfer
const creditTransfer = {
  CreditTransfer: {
    Debtor: {
      Name: "Sender Name",
      AccountNumber: "123456",
      AccountType: "Checking"
    },
    Creditor: {
      Name: "Recipient Name",
      AccountNumber: "789012",
      RoutingNumber: "111000025"
    },
    CreditTransferDescription: {
      Amount: 100.00,
      OriginatorType: "BUSINESS",
      UserName: "User123",
      Notes: "Payment for invoice"
    }
  }
};

const response = await client.createCreditTransfer(creditTransfer);
console.log('Transfer created:', response);

🔍 Key Concepts

Local vs Remote Accounts

• Local Account (PayerAccount): Internal accounts within your institution

  • Required fields: Name, AccountNumber, AccountType
  • No routing number needed (inferred by the system)

• Remote Account (RemoteAccount): External accounts at other institutions

  • Required fields: Name, AccountNumber, RoutingNumber
  • Routing number is mandatory for network routing

Credit Transfer Parties

• Debtor: The party sending funds (uses PayerAccount schema)
• Creditor: The party receiving funds (uses RemoteAccount schema)

Payment Request Parties

• Creditor: The party requesting funds (uses PayerAccount schema)
• Debtor: The party being asked to pay (uses RemoteAccount schema)

Idempotency

All POST and PATCH requests support idempotency via the X-Request-ID header. The client automatically generates a UUID v4 if not provided, ensuring safe retries without duplicate transactions.

🛠 Troubleshooting

Missing Configuration Error

Missing required configuration: clientId, clientSecret, institutionId

Solution: Ensure your .env file exists and contains all required credentials.

Authentication Failed

✗ Authentication failed: Request failed with status code 401

Solution: Verify your PIPA_CLIENT_ID and PIPA_CLIENT_SECRET are correct.

Invalid Routing Number

Routing eligibility check failed

Solution: Ensure the routing number is exactly 9 digits and eligible for PIPA transactions.

🔐 Security Best Practices

1. Never commit .env file: The .gitignore prevents this by default
2. Rotate credentials regularly: Change your client secrets periodically
3. Use environment-specific credentials: Separate credentials for sandbox and production
4. Secure credential storage: Consider using a secrets manager in production

---

📝 License

MIT

📥 Downloads

Download the complete Node.js implementation:

• Download Node.js Sample (ZIP) - Complete Node.js client with demo application

What's included:

• PIPAPayCenterClient.js - Main API client implementation
• index.js - Demo application with all API operations
• config.js - Configuration management
• Sample JSON payloads for all operations
• .env.example - Environment variables template

After downloading:

1. Extract the ZIP file
2. Run npm install to install dependencies
3. Copy .env.example to .env and configure your credentials
4. Run npm start to execute the demo

🤝 Support

For API support, please contact your PIPA PayCenter representative.