Overview

The JH PayCenter Instant Payment Request API enables Financial Institutions (FIs) and their partners to create and manage the complete Payment Request lifecycle. This includes initiating payment requests to debtors, processing debtor responses (acceptance/rejection), and tracking status across supported real-time payment networks.

Payment Request APIs

1. Payment Request API
2. Respond to Payment Request API
3. Get Payment Request API

1. Payment Request API

The Payment Request API allows financial institutions to initiate Payment Request messages. This enables creditors to request funds from debtors through supported instant payment networks, providing a secure and standardized method for payment collection.

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 creditor account inquiry is performed to validate and verify account details.
• If the request passes all validations, a Payment Request (pain.013) message is constructed and sent to the Instant Payments Network.
• The API responds with a 'PmtHubTrakId' and a status of 'Pending', indicating that the Payment Request has been successfully submitted to the network.
• The debtor's financial institution receives the Payment Request, and the debtor can respond by either Accepting or Rejecting it.
• Based on the debtor’s action, PayCenter sends EES 800 events through the JHA EES system with status updates:
  • Accepted (Acpt) – Payment Request accepted by debtor
  • Rejected (Rej) – Payment Request rejected by debtor or network
  • Expired (Cancel) – Payment Request expired without response
• When an associated payment is received (following Payment Request acceptance), PayCenter sends additional EES 800 events with payment settlement information.

If a failure occurs at any stage (authorization, validation), 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	Creditor Name	140	RequestForPayment.Creditor.Name	Required
AccountNumber	String	Creditor Account Number	34	RequestForPayment.Creditor.AccountNumber	Required
AccountType	String	Creditor Account Type (Enum: Checking, Savings, MICR)	NA	RequestForPayment.Creditor.AccountType	Required
Name	String	Ultimate Creditor Name. See Rules section	140	RequestForPayment.Creditor.UltimateCreditor.Name	Optional
Name	String	Debtor Name	140	RequestForPayment.Debtor.Name	Required
RoutingNumber	String	Debtor Routing Number	9	RequestForPayment.Debtor.RoutingNumber	Required
AccountNumber	String	Debtor Account Number	34	RequestForPayment.Debtor.AccountNumber	Required
Name	String	Ultimate Debtor Name	140	RequestForPayment.Debtor.UltimateDebtor.Name	Optional
Amount	Number	Amount to be transferred (Min: $0.01). See Rules section	-	RequestForPayment.PaymentDescription.Amount	Required
OriginatorType	String	Defines the Originator Type (Enum: CONSUMER, BUSINESS, GOVERNMENT). See Rules section	-	RequestForPayment.PaymentDescription.OriginatorType	Required
UserName	String	Defines the name of the user who initiated the Payment Request	35	RequestForPayment.PaymentDescription.UserName	Required
IsAmountModifyAllowed	Boolean	Indicates whether amount modification is allowed. See Rules section	-	RequestForPayment.PaymentDescription.IsAmountModifyAllowed	Required
PaymentDueDate	String	Payment due date. See Rules section	70	RequestForPayment.PaymentDescription.PaymentDueDate	Required
Notes	String	Free text	140	RequestForPayment.PaymentDescription.Notes	Optional

Rules

• UltimateCreditor Name:
  • If provided, OriginatorType must be BUSINESS or GOVERNMENT.
  • FedNow: Supported for BUSINESS and GOVERNMENT.
  • RTP: Supported for BUSINESS.
• Amount: Supports up to two decimal places. Maximum amount validation is based on network-specific limits.
• OriginatorType (CONSUMER): UltimateCreditor fields must not be provided.
  • FedNow & RTP: Supported for CONSUMER.
• OriginatorType (BUSINESS / GOVERNMENT): UltimateCreditor fields are optional.
• IsAmountModifyAllowed: If set to true, the debtor may modify the requested amount.
• PaymentDueDate: Format must be YYYY-MM-DD, allowing only the current date or a future date.

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 RequestForPayment object from the request. Refer to the field descriptions in the “Request Fields” section above

NOTE

• The initial Status will be 'Pending'.
• The status (Accepted or Rejected or Cancel) will be delivered through EES events.
• The X-Request-ID used in the request header is returned in every response header.

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 unique identifier of the original transaction request.
• Status: Returns the status of the original transaction request.

2. Respond to Payment Request API

The Respond to Payment Request API enables Debtor Financial Institutions to process and respond to Payment Requests received through the Instant Payments Network. This API allows the debtor’s institution to accept or reject incoming Payment Requests, completing the response stage of the Payment Request lifecycle.

Key Features

• Accept: Allows debtors to approve Payment Requests and proceed with fund transfer initiation
• Reject: Allows debtors to decline Payment Requests with appropriate reason code
• Amount Modification: Support partial payments when allowed by the original Payment Request

Workflow

• A PATCH API request is sent with the required body and authorization containing the debtor's response.
• The request is validated by the API's business layer.
• If the request passes all validations, a Respond to Payment Request (pain.014) message is constructed and sent to the Instant Payments Network.
• The API responds with a status of 'Initiated', indicating that the response has been successfully submitted to the network.
• If the Payment Request is accepted by the debtor, the financial institution can proceed to initiate the associated payment transfer.
• PayCenter sends EES 800 events to notify the response status and any subsequent payment processing.

Request Fields

Fields	Type	Description	Max Len	Path	Req/Opt
Status	String	Debtor's response status (Enum: Accepted, Rejected)	140	Status	Required
Amount	String	Amount accepted by the Debtor. See Rules section	34	Amount	Conditional
ReasonCode	String	Reason for rejection. See Rules section	NA	ReasonCode	Conditional
Notes	String	Free text	140	Notes	Optional
UserName	String	Defines the name of the user who initiated the request	35	UserName	Required

Rules

• PmtHubTrakId: Provide the PmtHubTrakId from the inbound Payment Request (pain.013) received via the EES 800 event.

• Amount: Required only if the Status is 'Accepted'.

• ReasonCode: Required only if the Status is 'Rejected'. The code must be one of the following valid values:

  FedNow Supported Reason Codes

  Code	Description
  AC06	Blocked Account
  AG01	Transaction forbidden
  AG03	Transaction not Supported
  AM14	Amount Exceeds
  BE04	Invalid Creditor Information
  BE07	Invalid Debtor Information
  CH11	Creditor Identifier Incorrect
  DS04	Order Rejected
  MD07	Invalid Customer Information
  AM09	Invalid amount
  CUST	Requested by customer
  NARR	Custom narrative (details provided separately)

  RTP Supported Reason Codes

  Code	Description
  AC06	Blocked Account Number
  AG01	Forbidden Account Number
  AG03	Unauthorized Account Number
  AM09	Wrong Amount
  AM14	Transaction Limit Exceeded
  BE04	Invalid Creditor Information
  BE07	Invalid Debitor Information
  CH11	Creditor Identifier Incorrect
  CUST	Requested By Customer
  DS04	Order Rejected
  MD07	Invalid Customer Information
  NARR	Reason is provided as narrative information.
  SL12	Debtor has indicated it does not wish to receive RFPs from the Creditor.

Success Response Fields

Fields	Type	Description	Path
Status	String	Status of the response	Status
Description	String	Detailed status description	Description

NOTE

• The initial status will be 'Initiated'.
• The status of the transaction (Accepted or Rejected) will be provided through EES events.

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

3. Get Payment Request API

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

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 layer.
• The system looks up the payment request using either the PmtHubTrakId or X-Request-ID.
• If the payment request exists and is within the last 30 days, the corresponding details are returned.
• If the payment request does not exist, is older than 30 days, 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 Request by PmtHubTrakId

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

II. Get Payment Request by X-Request-ID

• Passed as a Query Parameter.
• Use the X-Request-ID unique identifier (UUID) sent in the original Payment Request 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	Creditor routing number	SenderRTN	Required
SenderAccountNumber	String	Creditor account number (partially masked)	SenderAccountNumber	Required
SenderAccountType	String	Creditor account type (Enum: Checking, Savings, MICR)	SenderAccountType	Required
SenderName	String	Creditor name	SenderName	Required
ReceiverRTN	String	Debtor routing number	ReceiverRTN	Required
ReceiverAccountNumber	String	Debtor account number (partially masked)	ReceiverAccountNumber	Required
ReceiverAccountType	String	Debtor account type (Enum: Checking, Savings, MICR)	ReceiverAccountType	Required
ReceiverName	String	Debtor name	ReceiverName	Required
UltimateCreditorName	String	Ultimate creditor name	UltimateCreditorName	Required
UltimateDebtorName	String	Ultimate debtor name	UltimateDebtorName	Required
RequestAmount	Number	Requested payment amount	RequestAmount	Required
IsPaymentModificationAllowed	Boolean	Amount modification permission flag	IsPaymentModificationAllowed	Required
PaymentDueDate	String	Payment due date (YYYY-MM-DD)	PaymentDueDate	Required
Status	String	Payment request status (Enum: Pending, Accepted, Rejected, Expired, Failed, Completed)	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
Payment	Object	Associated payment details (when Status is Completed)	Payment	Optional
TransactionReceiptId	String	Payment receipt identifier	Payment.TransactionReceiptId	Optional
NetworkPrimaryReferenceId	String	Payment network reference identifier	Payment.NetworkPrimaryReferenceId	Optional
PmtHubTrakId	String	Payment transaction identifier	Payment.PmtHubTrakId	Optional
TransactionAmount	Number	Actual payment amount	Payment.TransactionAmount	Optional
Status	String	Payment transaction status (Enum: Pending, Accepted, Rejected)	Payment.Status	Optional

NOTE

• Status Values:
  • Pending - Payment request is awaiting debtor response
  • Accepted - Payment request was accepted by the debtor
  • Rejected - Payment request was rejected by the debtor or network
  • Expired - Payment request exceeded the due date without response
  • Failed - Payment request failed due to system error or validation failure
  • Completed - An associated payment was received
• Transaction details can be retrieved for a maximum of 30 days from the date the payment request 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