Overview

This document is the "Source of Truth" for AI-native development. It combines business logic, the full OpenAPI 3.1 spec, and agentic instructions.

---

🚀 1. Strategic Implementation Rules (For AI Agents)

• Account Schema Distinction:
  • Local Party (PayerAccount): Always use Name, AccountNumber, and AccountType. Never include a routing number.
  • Remote Party (RemoteAccount): Always use Name, AccountNumber, and RoutingNumber.
• Header Requirement: Every POST and PATCH request MUST include a unique UUID v4 in the X-Request-ID header.
• Authentication: Access tokens are obtained via OAuth2 Client Credentials at https://ipa01.eagle.jhapaycenter.com/token. Use application/x-www-form-urlencoded.

---

💳 2. Direct Credit Transfer Workflow

1. Auth: Get Bearer token.
2. Transfer: POST to /credit-transfers.
   • Debtor = PayerAccount (Local).
   • Creditor = RemoteAccount (Remote).

---

📩 3. Request for Payment (RfP) Workflow

1. Initiate: POST to /payment-requests.
   • Creditor = PayerAccount (Local).
   • Debtor = RemoteAccount (Remote).
2. Accept: Debtor must PATCH the request status to Accepted.
3. Pay: POST to /credit-transfers.
   • Critical: Map the trackId from the RfP response into CreditTransfer.PaymentRequestDetails.RfPPmtHubTrakId.

---

🤖 4. Complete OpenAPI 3.1 Specification

openapi: 3.1.0
info:
  title: PIPA PayCenter API
  version: 1.0.0
servers:
  - url: https://ipa01.eagle.jhapaycenter.com
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://ipa01.eagle.jhapaycenter.com/token
  schemas:
    PayerAccount:
      type: object
      required: [Name, AccountNumber, AccountType]
      properties:
        Name: { type: string, example: "PC-Vinoth" }
        AccountNumber: { type: string, example: "556677" }
        AccountType: { type: string, enum: [Checking, Savings] }
    RemoteAccount:
      type: object
      required: [Name, AccountNumber, RoutingNumber]
      properties:
        Name: { type: string, example: "PC-Test" }
        AccountNumber: { type: string, example: "201990001" }
        RoutingNumber: { type: string, example: "711060274", pattern: '^\d{9}$' }
    CreditTransferRequest:
      type: object
      required: [CreditTransfer]
      properties:
        CreditTransfer:
          type: object
          required: [Debtor, Creditor, CreditTransferDescription]
          properties:
            Debtor: { $ref: '#/components/schemas/PayerAccount' }
            Creditor: { $ref: '#/components/schemas/RemoteAccount' }
            CreditTransferDescription:
              type: object
              required: [Amount, OriginatorType]
              properties:
                Amount: { type: number, format: float, example: 1.01 }
                OriginatorType: { type: string, enum: [BUSINESS, INDIVIDUAL] }
            PaymentRequestDetails:
              type: object
              properties:
                RfPPmtHubTrakId: { type: string, example: "202602061DCM3173825714" }
    PaymentRequestObject:
      type: object
      required: [RequestForPayment]
      properties:
        RequestForPayment:
          type: object
          required: [Creditor, Debtor, PaymentDescription]
          properties:
            Creditor: { $ref: '#/components/schemas/PayerAccount' }
            Debtor: { $ref: '#/components/schemas/RemoteAccount' }
            PaymentDescription:
              type: object
              properties:
                Amount: { type: number, example: 1.01 }
                OriginatorType: { type: string, example: "BUSINESS" }
                PaymentDueDate: { type: string, format: date }
    PaymentResponseUpdate:
      type: object
      required: [Status]
      properties:
        Status: { type: string, enum: [Accepted, Rejected] }
        Amount: { type: number }
        ReasonCode: { type: string }
        Notes: { type: string }

paths:
  /token:
    post:
      operationId: getAccessToken
      security: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type: { type: string, default: client_credentials }
      responses: { '200': { description: "Success" } }
  /v2/paycenter/institutions/{institutionId}/environments/sandbox/products/pipa/credit-transfers:
    post:
      operationId: createCreditTransfer
      parameters:
        - name: X-Request-ID
          in: header
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreditTransferRequest' }
      responses: { '202': { description: "Accepted" } }
    get:
      operationId: getCreditTransferByRequestId
      parameters:
        - name: x-request-id
          in: query
          required: true
          schema: { type: string }
      responses: { '200': { description: "Success" } }
  /v2/paycenter/institutions/{institutionId}/environments/sandbox/products/pipa/credit-transfers/{trackId}:
    get:
      operationId: getCreditTransferByTrackId
      parameters:
        - name: institutionId
          in: path
          required: true
          schema: { type: string }
        - name: trackId
          in: path
          required: true
          schema: { type: string }
      responses: { '200': { description: "Success" } }
  /v2/paycenter/environments/sandbox/products/pipa/financial-institutions:
    get:
      operationId: getRoutingEligibility
      parameters:
        - name: routingnumber
          in: query
          required: true
          schema: { type: string }
      responses: { '200': { description: "Success" } }
  /v2/paycenter/institutions/{institutionId}/environments/sandbox/products/pipa/payment-requests:
    post:
      operationId: createPaymentRequest
      parameters:
        - name: X-Request-ID
          in: header
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PaymentRequestObject' }
      responses: { '201': { description: "Created" } }
    get:
      operationId: getPaymentRequestByRequestId
      parameters:
        - name: x-request-id
          in: query
          required: true
          schema: { type: string }
      responses: { '200': { description: "Success" } }
  /v2/paycenter/institutions/{institutionId}/environments/sandbox/products/pipa/payment-requests/{trackId}:
    get:
      operationId: getPaymentRequestByTrackId
      parameters:
        - name: institutionId
          in: path
          required: true
          schema: { type: string }
        - name: trackId
          in: path
          required: true
          schema: { type: string }
      responses: { '200': { description: "Success" } }
  /v2/paycenter/institutions/{institutionId}/environments/sandbox/products/pipa/payment-requests/{trackId}/response:
    patch:
      operationId: updatePaymentStatus
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PaymentResponseUpdate' }
      responses: { '200': { description: "Updated" } }

---

🛠 5. .cursorrules (Agent Behavior Configuration)

Copy this content into a .cursorrules file in your root directory.

# PIPA API Behavior Guardrails

- **Mandatory Header**: Every POST/PATCH request must include 'X-Request-ID' header with a new UUID v4.
- **Token Fetching**: Use 'application/x-www-form-urlencoded' for /token.
- **Account Logic**:
    - For CreditTransfer: Debtor is Local (No Routing), Creditor is Remote (Has Routing).
    - For PaymentRequest: Creditor is Local (No Routing), Debtor is Remote (Has Routing).
- **RfP Sequence**: Do not call POST /credit-transfers with RfPPmtHubTrakId unless the request status is already 'Accepted'.