Skip to main content

Overview

The JH PayCenter API manages transaction limit rules for Zelle payment participants. It allows Financial Institutions (FIs) and their partners to create, read, update, and delete per-user spending limits (funding caps and velocity controls) scoped by direction and time range, and to view limits configured at the institution level.

BATCH PROCESSING NOT SUPPORTED

The PayCenter Supporting Services APIs are designed to process one request at a time and do not support batch processing. Each API call must be made individually and sequentially.

Sending a high volume of concurrent requests — such as thousands of simultaneous connections — may result in:

  • Rate limiting or throttling of your client application
  • Degraded response times for all active requests
  • Rejected connections due to server-side resource constraints

Clients must implement a sequential request pattern, issuing one call at a time and waiting for the response before submitting the next. For high-volume workloads, incorporate appropriate back-off and retry strategies to handle transient errors gracefully.

PayCenter Supporting Service APIs

  1. Get User Limits
  2. Add User Limits
  3. Update User Limits
  4. Delete User Limits
  5. Get FI Limits

Prerequisites​

  • The calling institution must have a valid 9-digit routing number registered in the PayCenter system.
  • The PaymentNetwork header must be Zelle. No other networks are currently supported.
  • All requests require the standard correlation, request, and audit headers (see Common Request Headers below).

Endpoint Routes​

All PayCenter Supporting Service API endpoints follow the path structure below. The paths are relative to the base service URL (see Service Endpoints).

OperationMethodPath
Get User LimitsGET/api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits
Add User LimitsPOST/api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits
Update User LimitsPUT/api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits
Delete User LimitsDELETE/api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits
Get FI LimitsGET/api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/financial-institution/limits

Common Path Parameters​

ParameterTypeRequiredDescription
routingNumberStringRequired9-digit ABA routing/transit number of the FI. Must be numeric and not all zeros.
envStringRequiredTarget environment name. Valid values: sandbox or production. Must match the configured environment value.

Common Request Headers​

Every request must include the following custom headers. Requests missing any of these headers receive a 400 Bad Request before reaching the controller.

HeaderTypeDescriptionReq/Opt
AuthorizationStringBearer token. Authorization: Bearer {access_token} — obtain from the /token endpoint.Required
Content-TypeStringMust be application/json for requests with a body.Required
PaymentNetworkStringMust be Zelle (case-insensitive).Required
X-Correlation-IDString (UUID)Caller-supplied correlation identifier for distributed tracing. Should be unique per process.Required
X-Request-IDString (UUID)Caller-supplied unique request identifier. Should be unique per request.Required
X-AuditUserIdStringUser ID of the operator performing the action, used for audit logging.Required

Data Types Reference​

The following enums and value sets are referenced throughout the PayCenter Supporting Service APIs.

LimitScope​

ValueDescription
UserLimit applies to an individual user.
InstitutionLimit applies to the institution as a whole.

LimitsDirection​

ValueDescription
InboundMoney coming in to the user.
OutboundMoney going out from the user.
NOTE

Currently, Get/Add/Update/Delete operations only support Outbound. Inbound mutations are not yet supported.

LimitType​

ValueDescription
FundingCapMaximum dollar amount allowed.
FundingVelocityMaximum number of transactions allowed.

LimitRange​

ValueDescription
PerTransactionLimit applied per individual transaction.
DailyRolling 24-hour limit.
SevenDaysRolling 7-day limit.
ThirtyDaysRolling 30-day limit.

ExternalIdentifierType​

ValueDescription
TokenUser's Zelle token name.
TaxIdUser's Tax ID. Only Social Security Number (SSN) is currently supported.

Audit Events​

Every successful mutation emits an audit event:

EventDescription
OutboundLimitsAddedOutbound limits were created for a user.
OutboundLimitsUpdatedOutbound limits were updated for a user.
OutboundLimitsDeletedOutbound limits were deleted for a user.

1. Get User Limits​

The Get User Limits endpoint retrieves the current limit rules configured for a specific user, identified by an external identifier and type. Supports both Token and TaxId (SSN only) as identifier types.

Workflow​

  • A GET API request is sent with the required headers and authorization.
  • The request is validated by the API's business layer.
  • The institution's routing number is verified against the Zelle organization registry.
  • The system looks up the user using ExternalIdentifier and ExternalIdentifierType headers.
  • The current outbound limits for the user are returned in the response.
  • If the user has no configured limits, an empty outboundLimits array is returned.

High-Level Diagram​

Request Headers​

In addition to the Common Request Headers:

HeaderTypeDescriptionReq/Opt
LimitScopeStringMust be User. (Enum: User)Required
ExternalIdentifierStringThe user's external identifier value (token name or tax ID).Required
ExternalIdentifierTypeStringType of the external identifier. (Enum: Token, TaxId — SSN only)Required
DirectionStringMust be Outbound. (Enum: Outbound)Required
CoreCustomerIDStringCore system customer identifier. If provided, must not be blank. See Rules sectionOptional
ProductTypeStringCustomer profile type. (Enum: P2P, SMB) See Rules sectionOptional

Request Body​

None — all parameters are supplied via headers.

Rules
  • CoreCustomerID: When supplied, must contain non-whitespace characters.
  • ProductType: Required when the institution has SMB enabled. Accepted values are P2P and SMB.

Success Response Fields​

FieldsTypeDescription
limitScopeStringScope of the returned limits (User).
identifierStringThe user's identifier value (the ExternalIdentifier sent in the request).
externalIdentifierTypeStringIdentifier type (Enum: Token, TaxId — SSN only).
coreCustomerIDStringThe core customer identifier echoed from the request. Omitted when null.
productTypeStringThe customer profile type echoed from the request (Enum: P2P, SMB). Omitted when null.
outboundLimitsArrayArray of outbound limit rules.
limitIdIntegerInternal identifier of the limit record.
typeStringLimit type (Enum: FundingCap, FundingVelocity).
rangeStringLimit range (Enum: PerTransaction, Daily, SevenDays, ThirtyDays).
limitValueNumberThe configured limit amount or transaction count.
createdDateTimeUTCStringISO 8601 timestamp when the limit was created.
modDateTimeUTCStringISO 8601 timestamp of the last modification.
NOTE
  • coreCustomerID and productType are only present in the response when they were supplied in the request.
  • The X-Request-ID and X-Correlation-ID sent in the request headers are returned in every response header.

Failure Response Fields​

FieldsTypeDescriptionReq/Opt
responseCodeIntegerHTTP status code mirror.Required
descriptionStringOverall error description.Required
messageSourceStringSource of the error (e.g. PayCenter API).Required
detailsArrayList of specific validation or system errors.Required
codeStringProduct-specific error code (e.g. PA-1003).Required
categoryStringError classification (Enum: Error, Fault, Warning, Overridden).Required
descriptionStringDescription of the specific error detail.Required
elementStringJSON or header field causing the issue. May be empty.Required
elementValueStringProblematic field value. May be empty.Required
locationStringPath location of the error. May be empty.Required

2. Add User Limits​

The Add User Limits endpoint creates one or more limit rules for a user. On success, returns the current limits for that user. Emits an OutboundLimitsAdded audit event.

Workflow​

  • A POST API request is sent with the required headers, body, and authorization.
  • The request is validated by the API's business layer.
  • The institution's routing number is verified against the Zelle organization registry.
  • The system checks for existing limits with the same type and range for the user — duplicates return a 409 Conflict.
  • If validation passes, the new limit rules are persisted to the datastore.
  • The current set of outbound limits for the user is returned in the response.
  • An OutboundLimitsAdded audit event is published.

High-Level Diagram​

Request Headers​

Only the Common Request Headers are required. All other fields are sent in the request body.

Request Fields​

FieldsTypeDescriptionReq/Opt
limitScopeStringScope of the limits. (Enum: User) See Rules sectionRequired
externalIdentifierStringThe user's external identifier value.Required
externalIdentifierTypeStringType of the external identifier. (Enum: Token, TaxId — SSN only)Required
directionStringDirection of the limits. (Enum: Outbound) See Rules sectionRequired
limitsArrayAt least one limit entry.Required
typeStringLimit type. (Enum: FundingCap, FundingVelocity)Required
rangeStringLimit range. (Enum: PerTransaction, Daily, SevenDays, ThirtyDays)Required
limitValueNumberLimit amount. Must be greater than 0.Required
coreCustomerIDStringCore system customer identifier. If provided, must not be blank. See Rules sectionOptional
productTypeStringCustomer profile type. (Enum: P2P, SMB) See Rules sectionOptional
Rules
  • limitScope: Only User is accepted for mutations. Institution-scoped limits are read-only.
  • direction: Only Outbound is currently supported for mutations. Inbound limits are not yet supported.
  • limitValue: Must be greater than 0. For FundingCap, supports up to two decimal places. For FundingVelocity, represents a whole-number transaction count.
  • CoreCustomerID: When supplied, must contain non-whitespace characters.
  • ProductType: Required when the institution has SMB enabled. Accepted values are P2P and SMB.
  • Duplicate Detection: A limit with the same type and range cannot be added twice for the same user — use Update User Limits instead.

Success Response Fields​

Returns the same shape as Get User Limits — Success Response Fields. The response reflects the current set of limits for the user after the new rules have been persisted.

NOTE
  • The initial set of limits returned in the response is the complete current set, not only the newly added rules.
  • The X-Request-ID used in the request header is returned in every response header.
  • A corresponding OutboundLimitsAdded audit event is emitted for every successful add.

Failure Response Fields​

Same shape as Get User Limits — Failure Response Fields. Refer to Error Codes for the full list of product-specific error codes.

3. Update User Limits​

The Update User Limits endpoint replaces existing limit rules for a user. On success, returns the updated set of limits. Emits an OutboundLimitsUpdated audit event.

Workflow​

  • A PUT API request is sent with the required headers, body, and authorization.
  • The request is validated by the API's business layer.
  • The institution's routing number is verified against the Zelle organization registry.
  • The system locates the existing limit rule for the user, matched by type and range.
  • If the rule is found, the limitValue is updated in the datastore.
  • If no matching rule exists, a 404 Not Found is returned — use Add User Limits instead.
  • The current set of outbound limits for the user is returned in the response.
  • An OutboundLimitsUpdated audit event is published.

High-Level Diagram​

Request Headers​

Only the Common Request Headers are required. All other fields are sent in the request body.

Request Fields​

FieldsTypeDescriptionReq/Opt
limitScopeStringScope of the limits. (Enum: User) See Rules sectionRequired
externalIdentifierStringThe user's external identifier value.Required
externalIdentifierTypeStringType of the external identifier. (Enum: Token, TaxId — SSN only)Required
directionStringDirection of the limits. (Enum: Outbound) See Rules sectionRequired
limitsArrayAt least one limit entry to update.Required
typeStringLimit type to update. (Enum: FundingCap, FundingVelocity)Required
rangeStringLimit range to update. (Enum: PerTransaction, Daily, SevenDays, ThirtyDays)Required
limitValueNumberNew limit amount. Must be greater than 0.Required
coreCustomerIDStringCore system customer identifier. If provided, must not be blank. See Rules sectionOptional
productTypeStringCustomer profile type. (Enum: P2P, SMB) See Rules sectionOptional
Rules
  • limitScope: Only User is accepted for mutations.
  • direction: Only Outbound is currently supported for mutations.
  • limitValue: Must be greater than 0.
  • CoreCustomerID: When supplied, must contain non-whitespace characters.
  • ProductType: Required when the institution has SMB enabled. Accepted values are P2P and SMB.
  • Existence Requirement: An existing rule with the same type and range must already exist for the user. If not, the API returns 404 Not Found (PA-1014).

Success Response Fields​

Returns the same shape as Get User Limits — Success Response Fields. The response reflects the current set of limits for the user after the update.

NOTE
  • The response returns the complete current set of limits, not only the modified rules.
  • The X-Request-ID used in the request header is returned in every response header.
  • A corresponding OutboundLimitsUpdated audit event is emitted for every successful update.

Failure Response Fields​

Same shape as Get User Limits — Failure Response Fields. Refer to Error Codes for the full list of product-specific error codes.

4. Delete User Limits​

The Delete User Limits endpoint removes specific limit rules for a user. Emits an OutboundLimitsDeleted audit event.

Workflow​

  • A DELETE API request is sent with the required headers, body, and authorization.
  • The request is validated by the API's business layer.
  • The institution's routing number is verified against the Zelle organization registry.
  • The system locates the existing limit rule(s) matched by type and range for the user.
  • If the rule is found, it is removed from the datastore.
  • If no matching rule exists, a 404 Not Found is returned.
  • An empty 200 OK response body is returned on success.
  • An OutboundLimitsDeleted audit event is published.

High-Level Diagram​

Request Headers​

Only the Common Request Headers are required. All other fields are sent in the request body.

Request Fields​

FieldsTypeDescriptionReq/Opt
limitScopeStringScope of the limits. (Enum: User) See Rules sectionRequired
externalIdentifierStringThe user's external identifier value.Required
externalIdentifierTypeStringType of the external identifier. (Enum: Token, TaxId — SSN only)Required
directionStringDirection of the limits. (Enum: Outbound) See Rules sectionRequired
limitsArrayAt least one limit entry identifying which rules to remove.Required
typeStringLimit type to delete. (Enum: FundingCap, FundingVelocity)Required
rangeStringLimit range to delete. (Enum: PerTransaction, Daily, SevenDays, ThirtyDays)Required
coreCustomerIDStringCore system customer identifier. If provided, must not be blank. See Rules sectionOptional
productTypeStringCustomer profile type. (Enum: P2P, SMB) See Rules sectionOptional
Rules
  • limitScope: Only User is accepted for mutations.
  • direction: Only Outbound is currently supported for mutations.
  • limitValue: Must not be supplied on delete — only type and range are required to identify the rule.
  • CoreCustomerID: When supplied, must contain non-whitespace characters.
  • ProductType: Required when the institution has SMB enabled.
  • Existence Requirement: A matching rule must exist for the user. If not, the API returns 404 Not Found (PA-1014).

Success Response Fields​

FieldsTypeDescription
(none)-The response body is empty on successful delete.
NOTE
  • The X-Request-ID used in the request header is returned in every response header.
  • A corresponding OutboundLimitsDeleted audit event is emitted for every successful delete.

Failure Response Fields​

Same shape as Get User Limits — Failure Response Fields. Refer to Error Codes for the full list of product-specific error codes.

5. Get FI Limits​

The Get FI Limits endpoint retrieves limit rules configured at the institution level (as opposed to per-user limits). This endpoint does not require an identifier because it returns limits for the institution as a whole.

Workflow​

  • A GET API request is sent with the required headers and authorization.
  • The request is validated by the API's business layer.
  • The institution's routing number is verified against the Zelle organization registry.
  • The system retrieves the configured institution-level outbound limits.
  • The current set of FI-level limits is returned in the response.
  • If the institution has no configured limits, an empty outboundLimits array is returned.

High-Level Diagram​

Request Headers​

In addition to the Common Request Headers:

HeaderTypeDescriptionReq/Opt
LimitScopeStringMust be Institution. (Enum: Institution)Required
DirectionStringMust be Outbound. (Enum: Outbound)Required
ProductTypeStringProduct type for which institution-level limits are retrieved. (Enum: P2P, SMB) See Rules sectionOptional

Request Body​

None — all parameters are supplied via headers.

Rules
  • LimitScope: Must be Institution for this endpoint.
  • Direction: Must be Outbound.
  • ProductType: Required when the institution has SMB enabled. Accepted values are P2P and SMB.

Success Response Fields​

FieldsTypeDescription
limitScopeStringAlways Institution for this endpoint.
productTypeStringThe product type for which institution-level limits were retrieved (Enum: P2P, SMB). Omitted when null.
outboundLimitsArrayArray of institution-level outbound limit rules.
limitIdIntegerInternal identifier of the limit record.
typeStringLimit type (Enum: FundingCap, FundingVelocity).
rangeStringLimit range (Enum: PerTransaction, Daily, SevenDays, ThirtyDays).
limitValueNumberThe configured limit amount or transaction count.
createdDateTimeUTCStringISO 8601 timestamp when the limit was created.
modDateTimeUTCStringISO 8601 timestamp of the last modification.
NOTE
  • productType is only present in the response when it was supplied in the request.
  • Unlike the user limits endpoints, the response does not include an identifier or externalIdentifier field — limits are institution-scoped.
  • The X-Request-ID and X-Correlation-ID sent in the request headers are returned in every response header.

Failure Response Fields​

Same shape as Get User Limits — Failure Response Fields. Refer to Error Codes for the full list of product-specific error codes.