Overview
Purpose
This document provides detailed reference information for the JH PayCenter Supporting Services API, helping users understand its APIs and their usage. The PayCenter Supporting Services API provides limit management capabilities for Zelle payment participants, enabling financial institutions to configure and manage transaction limits (funding caps and velocity controls) at the user level, and to view transaction limits at the institution level.
Who Can Use It
Financial institutions or partners using the JH PayCenter platform can use this API to manage per-user spending limits and view institution-level spending limits for Zelle transactions.
Environments
JH PayCenter provides two environments: Sandbox and Production.
-
Sandbox
- A production-like testing environment where you can safely integrate, test, and validate your application or solution before going live.
-
Production
- The live environment where your application or solution is launched. This environment supports real-time transactions and actual fund movement.
Service Endpoints
The following base URLs are used to access the Faster Payments APIs through the external API management gateway:
| Environment | Base URL |
|---|---|
| Sandbox | https://ipa01.eagle.jhapaycenter.com |
| Production | https://ipa01.tango.jhapaycenter.com |
Authentication Model
To access the JH PayCenter Supporting Services API, OAuth 2.0 is used as the authentication mechanism.
All requests require a Bearer access token obtained by exchanging your client credentials at the /token endpoint.
Token Generation
Send a POST request to the token endpoint:
| Property | Value |
|---|---|
| HTTP Method | POST |
| URL | https://ipa01.eagle.jhapaycenter.com/token (Sandbox) |
| Content-Type | application/x-www-form-urlencoded |
| Authorization | Basic {Base64(consumer-key:consumer-secret)} |
| Body | grant_type=client_credentials |
Response:
{
"access_token": "eyJ...",
"scope": "default",
"token_type": "Bearer",
"expires_in": 3600
}
Use the access_token as a Bearer token in the Authorization header of every API request:
Authorization: Bearer {access_token}
- Keep the access token secret.
- Tokens expire after the duration specified in
expires_in(typically 3600 seconds). - Generating a new token invalidates the previous one — only one active bearer token exists per application.
Please refer to the Authentication Framework section for detailed instructions on obtaining and using the required credentials.
Project Keys
The following table summarizes the keys and describes how they are used.
| Environment | Keys | Description |
|---|---|---|
| Sandbox | - Consumer Key - Consumer Secret | Private keys used for API authentication in the Sandbox environment |
| Production | - Consumer Key - Consumer Secret | Private keys used for API authentication in the Production environment |
JH PayCenter will provide the client credentials (consumer key and consumer secret) during onboarding.
Required Headers
Every request must include the following custom headers:
| Header | Required | Description |
|---|---|---|
Authorization | Required | Bearer token. Authorization: Bearer {access_token} — obtain from the /token endpoint. |
Content-Type | Required | Must be application/json for requests with a body. |
PaymentNetwork | Required | Must be Zelle (case-insensitive). |
X-Correlation-ID | Required | Caller-supplied correlation identifier (UUID) for distributed tracing. Should be unique per process. |
X-Request-ID | Required | Caller-supplied unique request identifier (UUID). Should be unique per request. |
X-AuditUserId | Required | User ID of the operator performing the action, used for audit logging. |
Endpoint Routes
All PayCenter API endpoints follow the path structure below. The paths are relative to the base URL above.
/api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/
API
The following are the API methods supported by the service.
| Methods | API | URL | Description |
|---|---|---|---|
| GET | Get User Limits | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits | Retrieve limits for a user |
| POST | Add User Limits | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits | Create limits for a user |
| PUT | Update User Limits | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits | Update limits for a user |
| DELETE | Delete User Limits | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/user/limits | Remove limits for a user |
| GET | Get FI Limits | /api/limits/v2/institutions/{routingNumber}/environments/{env}/products/faster-payments/financial-institution/limits | Retrieve institution-level limits |