Instant Payments (RTP / FedNow)

Rails: RTP (TCH) · FedNow (Federal Reserve) Settlement: Real-time (seconds) Reversible: No — irrevocable upon acceptance

The instant payments endpoint initiates real-time credit transfers via RTP (The Clearing House) or FedNow (Federal Reserve), 24 hours a day, 7 days a week. PayPlus automatically selects the appropriate rail based on the receiving bank's network participation, or you can specify a rail preference explicitly.

Irrevocability — Design Your Integration Accordingly Instant payments are irrevocable once accepted by the receiving bank. There is no reversal mechanism. If a customer initiates a payment in error, they must contact the beneficiary directly to request a voluntary return. Build confirmation steps into your user flow — never initiate an instant payment without explicit user confirmation of the beneficiary and amount.

Rail Behavior

Attribute	RTP (TCH)	FedNow
Max transaction amount	`100000000` ($1,000,000)	`50000000` ($500,000) default; `100000000` for eligible participants
Settlement	TCH joint account at FRBNY	Fed master account (direct)
Operating hours	24/7/365	24/7/365
Expected response time	< 10 seconds	< 20 seconds
Request for Payment	Yes (`rail: "rtp"`)	Yes (`rail: "fednow"`)
NSF returns	No — payment accepted regardless of receiver balance	No — same as RTP

Initiate an Instant Payment

POST /v2/payments/instant

Creates a real-time credit transfer. PayPlus performs OFAC screening, submits to the selected rail, and returns a final status (settled or failed) synchronously in the API response — typically within 10–20 seconds.

Synchronous Response Unlike ACH (which returns immediately with a validated status), the instant payment endpoint is synchronous — it holds the HTTP connection open until the payment is settled or has failed. Your HTTP client must have a timeout of at least 60 seconds for instant payment requests.

Request Body Parameters

Field	Type		Description
`amount`	integer	Required	Amount in cents (USD). Cannot exceed the rail maximum for the selected or auto-selected rail.
`railPreference`	string	Optional	Preferred rail: `"rtp"`, `"fednow"`, or `"auto"` (default). When `"auto"`, PayPlus applies the configured rail selection logic (see Rail Selection below).
`originator`	object	Required	Sending account. Fields: `name`, `accountNumber`, `accountType`, `routingNumber`, `address` (street, city, state, postalCode — required for BSA compliance).
`beneficiary`	object	Required	Receiving account. Fields: `name`, `accountNumber`, `accountType`, `routingNumber`, `address`.
`remittanceInfo`	string	Optional	Unstructured remittance information for the beneficiary. Passed in the pacs.008 `RmtInf` field. Maximum 140 characters.
`purposeCode`	string	Optional	ISO 20022 payment purpose code (e.g., `SALA` for salary, `RENT` for rent payment). Passed in pacs.008 `Purp` field.
`referenceId`	string	Optional	Your system's reference identifier. Maximum 35 characters.

Example Request

POST /v2/payments/instant HTTP/1.1
Host: api.payplus.yourbank.internal
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Content-Type: application/json
Idempotency-Key: 9b3c1d7e-2f4a-5b6c-8d9e-0f1a2b3c4d5e

{
  "amount": 50000,
  "railPreference": "auto",
  "originator": {
    "name": "John Doe",
    "accountNumber": "778899001122",
    "accountType": "checking",
    "routingNumber": "021000021",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001"
    }
  },
  "beneficiary": {
    "name": "Jane Smith",
    "accountNumber": "112233445566",
    "accountType": "checking",
    "routingNumber": "071000013",
    "address": {
      "street": "456 Oak Ave",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60601"
    }
  },
  "remittanceInfo": "Rent payment March 2026",
  "purposeCode": "RENT",
  "referenceId": "RENT-MAR2026-JD"
}

Response — Settled

200 OK (synchronous — response returned after settlement confirmation)

{
  "data": {
    "paymentId": "pmt_inst_b9c3d1f7e2a4",
    "rail": "fednow",
    "status": "settled",
    "amount": 50000,
    "uetr": "4a7f2b9c-3d1e-5f6a-8b9c-0d1e2f3a4b5c",
    "settlementTimestamp": "2026-03-15T14:30:07Z",
    "processingTimeMs": 5823,
    "referenceId": "RENT-MAR2026-JD",
    "createdAt": "2026-03-15T14:30:01Z"
  }
}

Response — Failed (Receiving Bank Return)

200 OK

{
  "data": {
    "paymentId": "pmt_inst_b9c3d1f7e2a4",
    "rail": "rtp",
    "status": "returned",
    "returnCode": "AC04",
    "returnReason": "Closed Account",
    "processingTimeMs": 8102
  }
}

Get Instant Payment Status

GET /v2/payments/instant/{paymentId}

Retrieves the current status of an instant payment. Because the POST /instant endpoint is synchronous, you typically have final status already in the initiation response. Use this endpoint for status reconciliation or if the initiation request timed out.

Send a Request for Payment (RfP)

POST /v2/payments/rfp

Sends a Request for Payment to another bank's customer. The recipient reviews the request and, if approved, initiates an RTP or FedNow credit transfer to fulfill it. The payer always controls the final payment decision — this is not a pull/debit mechanism.

Request Body Parameters

Field	Type		Description
`rail`	string	Required	Rail for the RfP message: `"rtp"` or `"fednow"`. The payer's bank must participate in the specified rail.
`amount`	integer	Required	Requested payment amount in cents (USD).
`dueDate`	string (date)	Optional	Payment due date in YYYY-MM-DD format. Informational — not enforced by the network.
`payee`	object	Required	Your account details (the party requesting payment). Fields: `name`, `accountNumber`, `accountType`, `routingNumber`.
`payer`	object	Required	The party being asked to pay. Fields: `name`, `accountNumber`, `accountType`, `routingNumber` (payer's bank).
`description`	string	Optional	Payment description shown to the payer. Maximum 140 characters.
`referenceId`	string	Optional	Your reference for this RfP (invoice number, etc.). Maximum 35 characters.

Example Request

POST /v2/payments/rfp HTTP/1.1
...

{
  "rail": "fednow",
  "amount": 125000,
  "dueDate": "2026-03-20",
  "payee": {
    "name": "ACME CORP",
    "accountNumber": "100020003000",
    "accountType": "checking",
    "routingNumber": "021000021"
  },
  "payer": {
    "name": "GLOBEX INDUSTRIES LLC",
    "accountNumber": "987654321",
    "accountType": "checking",
    "routingNumber": "071000013"
  },
  "description": "Invoice INV-2026-0042 — Software services March 2026",
  "referenceId": "INV-2026-0042"
}

Response

202 Accepted

{
  "data": {
    "rfpId": "rfp_fn_7a3b9c1d2e4f",
    "rail": "fednow",
    "status": "sent",
    "amount": 125000,
    "dueDate": "2026-03-20",
    "referenceId": "INV-2026-0042",
    "sentAt": "2026-03-15T09:00:00Z",
    "expiresAt": "2026-03-20T23:59:59Z"
  }
}

Get RfP Status

GET /v2/payments/rfp/{rfpId}

Returns the current status of a Request for Payment. Subscribe to the rfp.fulfilled webhook event to receive real-time notification when the payer completes the payment.

RfP Status	Description
`sent`	RfP delivered to payer's bank; awaiting payer action
`fulfilled`	Payer approved and payment has settled. `fulfillingPaymentId` field contains the instant payment ID.
`declined`	Payer explicitly declined the request
`expired`	RfP expired without payer action (past `dueDate` or 30 days, whichever is earlier)

Rail Selection Logic

When railPreference: "auto", PayPlus applies the following logic to select the best available rail:

// Simplified PayPlus rail selection pseudocode
if amount > 1_000_000:
    → route to Fedwire (instant rails do not support this amount)

if receivingBank participates in FedNow AND amount <= fednow_limit:
    → route to FedNow (preferred: direct Fed settlement, no prefunded balance risk)

elif receivingBank participates in RTP AND amount <= 1_000_000:
    → route to RTP

else:
    → return error INSTANT_RAIL_NOT_AVAILABLE
    → suggest routing to ACH or Fedwire instead

Configure custom rail selection rules in the PayPlus Admin Console at Administration > Workflow > Rail Selection Rules to override this default logic for specific scenarios (e.g., always prefer RTP for corporate accounts, always prefer FedNow for retail).

← ACH Payments Next: Wire Transfers →