Payment API

This document provides a comprehensive migration guide for transitioning from RTP to PIPA (PayCenter Instant Payments API) Payment API functionality.

It highlights all essential changes including endpoints, headers, request/response structures, identifiers, and error handling to ensure a smooth migration process.

1. Endpoint & Header

API Endpoint

Area	RTP	PIPA
HostName	Sandbox : wag01.eagle.jhapaycenter.com Production: wag01.tango.jhapaycenter.com	Sandbox : ipa01.eagle.jhapaycenter.com Production: ipa01.tango.jhapaycenter.com
URL	/v1/institutions/{senderrtn}/environments/{envname}/products/paycenter/networks/rtp/credit-transfers	/v2/paycenter/institutions/{senderrtn}/environments/{envname}/products/pipa/credit-transfers

Header

Header	RTP	PIPA
X-Request-ID	• Renamed as OriginatorReferenceId • Optional • Unique per request • Must follow UUID format • Returned in all response headers	• Required • Unique per request • Must follow UUID format • Returned in all response headers

2. Request Body

Debtor

Field	RTP	PIPA
Name	Optional	Required
AccountNumber	Required	Required
AccountType	Optional Allowed types: Checking, Savings, MICR	Required Allowed types: Checking, Savings, MICR
UltimateDebtor.Name	Optional	Optional
InitiatingParty	Optional	Optional

Creditor

Field	RTP	PIPA
Name	Required	Required
RoutingNumber	Required	Required
AccountNumber	Required	Required
UltimateCreditor.Name	Optional	Optional

CreditTransferDescription

Field	RTP	PIPA
Amount	Required	Required
TransferFee	Not Available	Optional
OriginatorType	Required Allowed types: CONSUMER, BUSINESS	Required Allowed types: CONSUMER, BUSINESS, GOVERNMENT
UserName	Required	Required
Notes	Optional	Optional

For more details:

• Refer Payment API

3. Response Body

Area	RTP	PIPA
Structure	Nested within CreditTransfer Object	Flattened structure with primary identifiers at the top level
Primary Identifier	CreditTransfer.Id	PmtHubTrakId
Status	CreditTransfer.Status	Status

For more details:

• Refer Payment API

4. Error Response

Area	RTP	PIPA
Structure	Simple object inside CreditTransfer	Standard PIPA error schema (consistent across all APIs)
Key Fields	Message, Error (Code, Description)	ResponseCode, Description, MessageSource, Details[], LogId
Code	Error.Code	Details[].Code
Description	Error.Description	Details[].Description

For more details:

• Refer Payment API

5. Duplicate Error Response

Area	RTP	PIPA
Original Transaction Identifier	CreditTransfer.OriginalTransactionDetails.Id	OriginalTransactionDetails.PmtHubTrakId
Status	CreditTransfer.OriginalTransactionDetails.Status	OriginalTransactionDetails.Status

For more details:

• Refer Payment API

6. Authentication Error Response

Area	RTP	PIPA
Structure	Returned in XML format	Returned in JSON format

For more details:

• Refer Payment API

7. EES & Events

Area	RTP	PIPA
Primary Identifiers	NetworkPrimaryReferenceId, TrnRcptId, PmtHubTrakId, X-Request-ID, PaymentIntegratorCode, PmtRailType	NetworkPrimaryReferenceId, TrnRcptId, PmtHubTrakId, X-Request-ID, PaymentIntegratorCode, PmtRailType
Events	Outbound - DrPmt/Dlvr, DrPmt/Acpt, DrPmt/Rej, DrPmt/Fail, CrPmt/Acpt Inbound - CrPmt/Acpt	Outbound - DrPmt/Acpt,DrPmt/Rej Inbound - CrPmt/Acpt

For more details:

• Refer Payment API -> EES Event 800

Migration Checklist

Quick Migration Steps

1. Update endpoints → Switch to PIPA hostnames and updated API paths.
2. Update headers → Use required X-Request-ID (UUID, unique per request) instead of optional OriginatorReferenceId.
3. Add required fields → Ensure Debtor.Name and Debtor.AccountType are provided as required in PIPA.
4. Handle new response → Use the flattened PIPA structure and read identifiers from PmtHubTrakId.
5. Update error handling → Implement the PIPA standard error schema (ResponseCode, Description, MessageSource, Details[], LogId).
6. Update authentication error handling → Expect JSON format instead of XML for authentication errors.
7. Update event handling → Adopt PIPA event types and structures for EES 800 events.