Overview

The JH PayCenter Instant Payments API enables Financial Institutions (FIs) and their partners to integrate real-time payment capabilities seamlessly, ensuring fast, efficient, and secure movement of funds across supported networks.

Payment APIs

1. Payment API
2. Get Payment API

1. Payment API

• The Payment API enables users to securely transfer funds from one bank account to another.
• Transactions can be initiated 24/7, providing flexibility and convenience. Financial institutions can use this API to allow customers to initiate payments efficiently through supported networks.

Workflow

• A POST API request is sent with the required headers, body, and authorization.
• The request is validated by the API's business layer.
• A debtor account inquiry is performed to validate and verify account details.
• A fraud check is triggered (if configured).
• If the request passes all validations, a debit transaction is initiated on the debtor’s account.
• Once the debit succeeds, a Credit Transfer message (pacs.008) is sent to the Instant Payments Network.
• The API responds with a 'PmtHubTrakId' and a status of 'Pending', indicating that the transaction has been submitted to the network.
• After the network processes the transaction, PayCenter sends EES 800 events through the JHA EES system with the final status:
  • Accepted (Acpt) – Payment settled
  • Rejected (Rej) – Payment failed
• If the transaction is rejected by the network or the creditor, the funds will be returned to the debtor’s account shortly.

If a failure occurs at any stage (authorization, validation, fraud check, or debit failure), the API will return an appropriate error response with specific error codes.

High-Level Diagram

Request Fields

Fields	Type	Description	Max Len	Path	Req/Opt
Name	String	Debtor Name	140	CreditTransfer.Debtor.Name	Required
AccountNumber	String	Debtor Account Number	34	CreditTransfer.Debtor.AccountNumber	Required
AccountType	String	Debtor Account Type (Enum: Checking, Savings, MICR)	NA	CreditTransfer.Debtor.AccountType	Required
Name	String	Ultimate Debtor Name. See Rules section	140	CreditTransfer.Debtor.UltimateDebtor.Name	Optional
InitiatingParty	String	Legal name of the party initiating payment instructions on behalf of the Debtor (RTP supported). See Rules section	140	CreditTransfer.Debtor.InitiatingParty	Optional
Name	String	Creditor Name	140	CreditTransfer.Creditor.Name	Required
RoutingNumber	String	Creditor Routing Number	9	CreditTransfer.Creditor.RoutingNumber	Required
AccountNumber	String	Creditor Account Number	34	CreditTransfer.Creditor.AccountNumber	Required
Name	String	Ultimate Creditor Name	140	CreditTransfer.Creditor.UltimateCreditor.Name	Optional
Amount	Number	Amount to be transferred (Min: $0.01). See Rules section	-	CreditTransfer.CreditTransferDescription.Amount	Required
TransferFee	Number	Transfer fee for the transaction. See Rules section	-	CreditTransfer.CreditTransferDescription.TransferFee	Optional
OriginatorType	String	Defines the Originator Type (Enum: CONSUMER, BUSINESS, GOVERNMENT). See Rules section	-	CreditTransfer.CreditTransferDescription.OriginatorType	Required
UserName	String	Defines the name of the user who initiated the transfer	35	CreditTransfer.CreditTransferDescription.UserName	Required
Notes	String	Free text	140	CreditTransfer.CreditTransferDescription.Notes	Optional
RfPPmtHubTrakId	String	PmtHubTrakId of the Inbound RfP. See Rules section	35	CreditTransfer.PaymentRequestDetails.RfPPmtHubTrakId	Conditional

Rules

• UltimateDebtor Name:
  • If provided, OriginatorType must be BUSINESS or GOVERNMENT.
  • FedNow: Supported for BUSINESS and GOVERNMENT.
  • RTP: Supported for BUSINESS.
• InitiatingParty: Supported for RTP use cases. FedNow OBO requirements do not require InitiatingParty and are governed by FedNow Operating Procedures.
• Amount: Supports up to two decimal places. Maximum amount validation is based on network-specific limits.
• TransferFee: Supports up to two decimal places. Applicable only for Payment transactions.
• OriginatorType (CONSUMER): UltimateDebtor fields must not be provided.
  • FedNow & RTP: CONSUMER is supported.
• OriginatorType (BUSINESS / GOVERNMENT): UltimateDebtor fields are optional.
• PaymentRequestDetails: Required only when making a payment against an inbound Payment Request (pain.013).
• RfPPmtHubTrakId: Provide the PmtHubTrakId from the inbound Payment Request (pain.013) received via the EES 800 event.

NOTE

• The X-Request-ID header is required for all payment requests.
• It must be a unique UUID.
• If a request is repeated using the same X-Request-ID, it will not be processed again and will return a duplicate error.

Success Response Fields

Fields	Type	Description	Path
PmtHubTrakId	String (35)	Unique ID per transaction	PmtHubTrakId
Status	String	Status of the transaction	Status
Other Fields	Object	Remaining fields mirror the CreditTransfer object from the request. Refer to the field descriptions in the "Request Fields" section above.

NOTE

• The initial status will be 'Pending'.
• The final status (Accepted or Rejected) will be delivered through EES events.
• The X-Request-ID used in the request header is returned in every response header.
• For Payment transactions, the TransferFee is returned in the response as provided in the request.
• For payments against inbound RfP transactions, the TransferFee field will not be returned in the response.

Failure Response Fields

Fields	Type	Description	Path	Req/Opt
ResponseCode	String	Product-specific error code	ResponseCode	Required
Description	String	Overall error description	Description	Required
MessageSource	String	Source of the error	MessageSource	Required
Details	Array	List of specific validation or system errors	Details	Required
Code	String	Error or fault code	Details[].code	Required
Category	String	Error classification (Enum: Error, Fault, Warning, Overridden)	Details[].Category	Required
Location	String	Field location in the payload. This value may be empty	Details[].Location	Required
Element	String	JSON field causing the issue. This value may be empty	Details[].Element	Required
ElementValue	String	Problematic field value. This value may be empty	Details[].ElementValue	Required
OriginalTransactionDetails	Object	Details of the original transaction when a duplicate request is detected. See Rules section	OriginalTransactionDetails	Optional
PmtHubTrakId	String	Existing transaction ID. See Rules section	OriginalTransactionDetails.PmtHubTrakId	Optional
Status	String	Status of the existing transaction (Enum: Pending, Failed, Accepted, Rejected, Completed, Expired). See Rules section	OriginalTransactionDetails.Status	Optional
LogId	String	Unique identifier for troubleshooting	LogId	Required

Rules

• OriginalTransactionDetails: Returned only when a duplicate request is identified through the X-Request-ID.
• PmtHubTrakId: Returns the transaction ID of the original transaction request.
• Status: Returns the status of the original transaction request.

NOTE

If the HTTP status code is 504 (Gateway Timeout), the transaction may have been processed by the network. Before retrying the payment request, it is recommended to call the Get Payment API by X-Request-ID to confirm the actual transaction status. Retrying the payment without verification may result in duplicate transactions.

2. Get Payment API

The Get Payment API retrieves the current status and detailed information for a previously submitted payment.

Workflow

• A GET API request is sent with the required path parameter or query parameter and authorization.
• The request is validated by the API's business layer.
• The system looks up the payment using either the PmtHubTrakId or X-Request-ID.
• If the payment is found, the API returns the details for requests created within the last 30 days.
• If the payment is not found or if validation fails, an appropriate error response is returned.

Lookup Methods

A transaction can be retrieved using one of the following unique identifiers:

I. Get Payment by PmtHubTrakId

• Passed as a Path Parameter.
• Use the PmtHubTrakId returned from the original Payment API.

II. Get Payment by X-Request-ID

• Passed as a Query Parameter.
• Use the X-Request-ID unique identifier (UUID) sent in the original Payment API header.

Success Response Fields

Fields	Type	Description	Path	Req/Opt
PmtHubTrakId	String	Unique transaction identifier	PmtHubTrakId	Required
NetworkPrimaryReferenceId	String	Network-assigned reference identifier	NetworkPrimaryReferenceId	Required
PmtRailType	String	Payment network type (Enum: FedNow, RTP)	PmtRailType	Required
EndtoEndId	String	End-to-end transaction identifier	EndtoEndId	Required
SenderRTN	String	Debtor routing number	SenderRTN	Required
SenderAccountNumber	String	Debtor account number (partially masked)	SenderAccountNumber	Required
SenderAccountType	String	Debtor account type (Enum: Checking, Savings, MICR)	SenderAccountType	Required
SenderName	String	Debtor name	SenderName	Required
ReceiverRTN	String	Creditor routing number	ReceiverRTN	Required
ReceiverAccountNumber	String	Creditor account number (partially masked)	ReceiverAccountNumber	Required
ReceiverAccountType	String	Creditor account type (Enum: Checking, Savings, MICR)	ReceiverAccountType	Required
ReceiverName	String	Creditor name	ReceiverName	Required
InitiatingParty	String	Initiating Party name	InitiatingParty	Required
UltimateCreditorName	String	Ultimate creditor name	UltimateCreditorName	Required
UltimateDebtorName	String	Ultimate debtor name	UltimateDebtorName	Required
TransactionReceiptId	String	Payment receipt identifier	TransactionReceiptId	Required
ReversalTransactionReceiptId	String	Reversal transaction receipt identifier (when applicable)	ReversalTransactionReceiptId	Required
Amount	Number	Actual payment amount	Amount	Required
TransferFee	Number	Transfer fee for the transaction	TransferFee	Required
Status	String	Payment status (Enum: Pending, Accepted, Rejected, Failed)	Status	Required
Reason	String	Rejection reason code (when Status is Rejected)	Reason	Required
Direction	String	Transaction direction (Enum: Inbound, Outbound)	Direction	Required
TransactionNotes	String	Additional transaction notes	TransactionNotes	Required
TransactionDate	String	Transaction creation timestamp	TransactionDate	Required

NOTE

• Status Values:
  • Pending - Payment is being processed by the network
  • Accepted - Payment was successfully settled
  • Rejected - Payment was rejected by the network or creditor
  • Failed - Payment failed at the API level
• Transaction details can be retrieved for a maximum of 30 days from the date the payment was created.

Failure Response Fields

Fields	Type	Description	Path	Req/Opt
ResponseCode	String	Product-specific error code	ResponseCode	Required
Description	String	Overall error description	Description	Required
MessageSource	String	Source of the error	MessageSource	Required
Details	Array	List of specific validation or system errors	Details	Required
Code	String	Error or fault code	Details[].code	Required
Category	String	Error classification (Enum: Error, Fault, Warning, Overridden)	Details[].Category	Required
Location	String	Field location in the payload. This value may be empty	Details[].Location	Required
Element	String	JSON field causing the issue. This value may be empty	Details[].Element	Required
ElementValue	String	Problematic field value. This value may be empty	Details[].ElementValue	Required
LogId	String	Unique identifier for troubleshooting	LogId	Required