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.
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
Prerequisites
- The calling institution must have a valid 9-digit routing number registered in the PayCenter system.
- The
PaymentNetworkheader must beZelle. 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).
| Operation | Method | Path |
|---|---|---|
| Get User Limits | GET | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits |
| Add User Limits | POST | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits |
| Update User Limits | PUT | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits |
| Delete User Limits | DELETE | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits |
| Get FI Limits | GET | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/financial-institution/limits |
Common Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
routingNumber | String | Required | 9-digit ABA routing/transit number of the FI. Must be numeric and not all zeros. |
env | String | Required | Target 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.
| Header | Type | Description | Req/Opt |
|---|---|---|---|
| Authorization | String | Bearer token. Authorization: Bearer {access_token} — obtain from the /token endpoint. | Required |
| Content-Type | String | Must be application/json for requests with a body. | Required |
| PaymentNetwork | String | Must be Zelle (case-insensitive). | Required |
| X-Correlation-ID | String (UUID) | Caller-supplied correlation identifier for distributed tracing. Should be unique per process. | Required |
| X-Request-ID | String (UUID) | Caller-supplied unique request identifier. Should be unique per request. | Required |
| X-AuditUserId | String | User 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
| Value | Description |
|---|---|
User | Limit applies to an individual user. |
Institution | Limit applies to the institution as a whole. |
LimitsDirection
| Value | Description |
|---|---|
Inbound | Money coming in to the user. |
Outbound | Money going out from the user. |
Currently, Get/Add/Update/Delete operations only support Outbound. Inbound mutations are not yet supported.
LimitType
| Value | Description |
|---|---|
FundingCap | Maximum dollar amount allowed. |
FundingVelocity | Maximum number of transactions allowed. |
LimitRange
| Value | Description |
|---|---|
PerTransaction | Limit applied per individual transaction. |
Daily | Rolling 24-hour limit. |
SevenDays | Rolling 7-day limit. |
ThirtyDays | Rolling 30-day limit. |
ExternalIdentifierType
| Value | Description |
|---|---|
Token | User's Zelle token name. |
TaxId | User's Tax ID. Only Social Security Number (SSN) is currently supported. |
Audit Events
Every successful mutation emits an audit event:
| Event | Description |
|---|---|
OutboundLimitsAdded | Outbound limits were created for a user. |
OutboundLimitsUpdated | Outbound limits were updated for a user. |
OutboundLimitsDeleted | Outbound 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
ExternalIdentifierandExternalIdentifierTypeheaders. - The current outbound limits for the user are returned in the response.
- If the user has no configured limits, an empty
outboundLimitsarray is returned.
High-Level Diagram
Request Headers
In addition to the Common Request Headers:
| Header | Type | Description | Req/Opt |
|---|---|---|---|
| LimitScope | String | Must be User. (Enum: User) | Required |
| ExternalIdentifier | String | The user's external identifier value (token name or tax ID). | Required |
| ExternalIdentifierType | String | Type of the external identifier. (Enum: Token, TaxId — SSN only) | Required |
| Direction | String | Must be Outbound. (Enum: Outbound) | Required |
| CoreCustomerID | String | Core system customer identifier. If provided, must not be blank. See Rules section | Optional |
| ProductType | String | Customer profile type. (Enum: P2P, SMB) See Rules section | Optional |
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
P2PandSMB.
Success Response Fields
| Fields | Type | Description |
|---|---|---|
| limitScope | String | Scope of the returned limits (User). |
| identifier | String | The user's identifier value (the ExternalIdentifier sent in the request). |
| externalIdentifierType | String | Identifier type (Enum: Token, TaxId — SSN only). |
| coreCustomerID | String | The core customer identifier echoed from the request. Omitted when null. |
| productType | String | The customer profile type echoed from the request (Enum: P2P, SMB). Omitted when null. |
| outboundLimits | Array | Array of outbound limit rules. |
| limitId | Integer | Internal identifier of the limit record. |
| type | String | Limit type (Enum: FundingCap, FundingVelocity). |
| range | String | Limit range (Enum: PerTransaction, Daily, SevenDays, ThirtyDays). |
| limitValue | Number | The configured limit amount or transaction count. |
| createdDateTimeUTC | String | ISO 8601 timestamp when the limit was created. |
| modDateTimeUTC | String | ISO 8601 timestamp of the last modification. |
coreCustomerIDandproductTypeare only present in the response when they were supplied in the request.- The
X-Request-IDandX-Correlation-IDsent in the request headers are returned in every response header.
Failure Response Fields
| Fields | Type | Description | Req/Opt |
|---|---|---|---|
| responseCode | Integer | HTTP status code mirror. | Required |
| description | String | Overall error description. | Required |
| messageSource | String | Source of the error (e.g. PayCenter API). | Required |
| details | Array | List of specific validation or system errors. | Required |
| code | String | Product-specific error code (e.g. PA-1003). | Required |
| category | String | Error classification (Enum: Error, Fault, Warning, Overridden). | Required |
| description | String | Description of the specific error detail. | Required |
| element | String | JSON or header field causing the issue. May be empty. | Required |
| elementValue | String | Problematic field value. May be empty. | Required |
| location | String | Path 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
typeandrangefor the user — duplicates return a409 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
OutboundLimitsAddedaudit 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
| Fields | Type | Description | Req/Opt |
|---|---|---|---|
| limitScope | String | Scope of the limits. (Enum: User) See Rules section | Required |
| externalIdentifier | String | The user's external identifier value. | Required |
| externalIdentifierType | String | Type of the external identifier. (Enum: Token, TaxId — SSN only) | Required |
| direction | String | Direction of the limits. (Enum: Outbound) See Rules section | Required |
| limits | Array | At least one limit entry. | Required |
| type | String | Limit type. (Enum: FundingCap, FundingVelocity) | Required |
| range | String | Limit range. (Enum: PerTransaction, Daily, SevenDays, ThirtyDays) | Required |
| limitValue | Number | Limit amount. Must be greater than 0. | Required |
| coreCustomerID | String | Core system customer identifier. If provided, must not be blank. See Rules section | Optional |
| productType | String | Customer profile type. (Enum: P2P, SMB) See Rules section | Optional |
- limitScope: Only
Useris accepted for mutations.Institution-scoped limits are read-only. - direction: Only
Outboundis currently supported for mutations. Inbound limits are not yet supported. - limitValue: Must be greater than
0. ForFundingCap, supports up to two decimal places. ForFundingVelocity, 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
P2PandSMB. - Duplicate Detection: A limit with the same
typeandrangecannot 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.
- The initial set of limits returned in the response is the complete current set, not only the newly added rules.
- The
X-Request-IDused in the request header is returned in every response header. - A corresponding
OutboundLimitsAddedaudit 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
typeandrange. - If the rule is found, the
limitValueis updated in the datastore. - If no matching rule exists, a
404 Not Foundis returned — use Add User Limits instead. - The current set of outbound limits for the user is returned in the response.
- An
OutboundLimitsUpdatedaudit 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
| Fields | Type | Description | Req/Opt |
|---|---|---|---|
| limitScope | String | Scope of the limits. (Enum: User) See Rules section | Required |
| externalIdentifier | String | The user's external identifier value. | Required |
| externalIdentifierType | String | Type of the external identifier. (Enum: Token, TaxId — SSN only) | Required |
| direction | String | Direction of the limits. (Enum: Outbound) See Rules section | Required |
| limits | Array | At least one limit entry to update. | Required |
| type | String | Limit type to update. (Enum: FundingCap, FundingVelocity) | Required |
| range | String | Limit range to update. (Enum: PerTransaction, Daily, SevenDays, ThirtyDays) | Required |
| limitValue | Number | New limit amount. Must be greater than 0. | Required |
| coreCustomerID | String | Core system customer identifier. If provided, must not be blank. See Rules section | Optional |
| productType | String | Customer profile type. (Enum: P2P, SMB) See Rules section | Optional |
- limitScope: Only
Useris accepted for mutations. - direction: Only
Outboundis 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
P2PandSMB. - Existence Requirement: An existing rule with the same
typeandrangemust already exist for the user. If not, the API returns404 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.
- The response returns the complete current set of limits, not only the modified rules.
- The
X-Request-IDused in the request header is returned in every response header. - A corresponding
OutboundLimitsUpdatedaudit 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
typeandrangefor the user. - If the rule is found, it is removed from the datastore.
- If no matching rule exists, a
404 Not Foundis returned. - An empty
200 OKresponse body is returned on success. - An
OutboundLimitsDeletedaudit 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
| Fields | Type | Description | Req/Opt |
|---|---|---|---|
| limitScope | String | Scope of the limits. (Enum: User) See Rules section | Required |
| externalIdentifier | String | The user's external identifier value. | Required |
| externalIdentifierType | String | Type of the external identifier. (Enum: Token, TaxId — SSN only) | Required |
| direction | String | Direction of the limits. (Enum: Outbound) See Rules section | Required |
| limits | Array | At least one limit entry identifying which rules to remove. | Required |
| type | String | Limit type to delete. (Enum: FundingCap, FundingVelocity) | Required |
| range | String | Limit range to delete. (Enum: PerTransaction, Daily, SevenDays, ThirtyDays) | Required |
| coreCustomerID | String | Core system customer identifier. If provided, must not be blank. See Rules section | Optional |
| productType | String | Customer profile type. (Enum: P2P, SMB) See Rules section | Optional |
- limitScope: Only
Useris accepted for mutations. - direction: Only
Outboundis currently supported for mutations. - limitValue: Must not be supplied on delete — only
typeandrangeare 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
| Fields | Type | Description |
|---|---|---|
| (none) | - | The response body is empty on successful delete. |
- The
X-Request-IDused in the request header is returned in every response header. - A corresponding
OutboundLimitsDeletedaudit 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
outboundLimitsarray is returned.
High-Level Diagram
Request Headers
In addition to the Common Request Headers:
| Header | Type | Description | Req/Opt |
|---|---|---|---|
| LimitScope | String | Must be Institution. (Enum: Institution) | Required |
| Direction | String | Must be Outbound. (Enum: Outbound) | Required |
| ProductType | String | Product type for which institution-level limits are retrieved. (Enum: P2P, SMB) See Rules section | Optional |
Request Body
None — all parameters are supplied via headers.
Rules- LimitScope: Must be
Institutionfor this endpoint. - Direction: Must be
Outbound. - ProductType: Required when the institution has SMB enabled. Accepted values are
P2PandSMB.
Success Response Fields
| Fields | Type | Description |
|---|---|---|
| limitScope | String | Always Institution for this endpoint. |
| productType | String | The product type for which institution-level limits were retrieved (Enum: P2P, SMB). Omitted when null. |
| outboundLimits | Array | Array of institution-level outbound limit rules. |
| limitId | Integer | Internal identifier of the limit record. |
| type | String | Limit type (Enum: FundingCap, FundingVelocity). |
| range | String | Limit range (Enum: PerTransaction, Daily, SevenDays, ThirtyDays). |
| limitValue | Number | The configured limit amount or transaction count. |
| createdDateTimeUTC | String | ISO 8601 timestamp when the limit was created. |
| modDateTimeUTC | String | ISO 8601 timestamp of the last modification. |
productTypeis only present in the response when it was supplied in the request.- Unlike the user limits endpoints, the response does not include an
identifierorexternalIdentifierfield — limits are institution-scoped. - The
X-Request-IDandX-Correlation-IDsent 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.