Introduction to the FedNow Service

The FedNow® Service, launched by the Federal Reserve in 2023, is the United States' new instant payment infrastructure. It allows financial institutions to send and receive payments around the clock, with final settlement in seconds. As a developer, you'll interact with FedNow through your financial institution's API gateway, which connects to the FedNow network using ISO 20022-based messaging.

This guide walks through the key concepts, message types, and code patterns you'll encounter when building on FedNow-connected infrastructure.

Prerequisites

  • Access to a FedNow-connected bank or fintech partner API
  • Sandbox credentials from your financial institution
  • Familiarity with REST APIs and JSON/XML
  • Understanding of OAuth 2.0 authentication

Understanding the ISO 20022 Message Format

FedNow uses the ISO 20022 financial messaging standard. Key message types you'll work with include:

Message Type ISO 20022 Code Purpose
Credit Transfer pacs.008 Initiate a payment from sender to receiver
Payment Return pacs.004 Return funds for a failed/rejected payment
Account Reporting camt.052 / camt.053 Retrieve account balance and transaction history
Payment Status Report pacs.002 Confirm accepted or rejected status of a payment

Step 1: Authenticate with Your API Gateway

Your institution's FedNow gateway will typically use OAuth 2.0 client credentials flow. Obtain your access token before making any payment requests:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=payments:write payments:read

Store the returned access_token securely. Tokens are short-lived — implement automatic refresh logic in your application.

Step 2: Initiate a Credit Transfer (pacs.008)

To send money, you'll submit a credit transfer request. While the actual ISO 20022 XML is verbose, most bank APIs expose a simplified JSON wrapper. A conceptual payload looks like this:

{
  "messageId": "MSG20250220001",
  "creationDateTime": "2025-02-20T10:30:00Z",
  "numberOfTransactions": 1,
  "settlementMethod": "CLRG",
  "creditTransfer": {
    "endToEndId": "E2E-2025-00123",
    "amount": { "value": 250.00, "currency": "USD" },
    "debtor": {
      "name": "Acme Corp",
      "accountNumber": "123456789",
      "routingNumber": "021000021"
    },
    "creditor": {
      "name": "Supplier LLC",
      "accountNumber": "987654321",
      "routingNumber": "026009593"
    },
    "remittanceInfo": "Invoice INV-2025-444"
  }
}

Step 3: Handle the Payment Status Response

FedNow responds synchronously with an initial acknowledgment and then sends a final status asynchronously. Listen for these status codes in your webhook handler:

  • ACCP — Accepted: Technical validation passed
  • ACSC — Accepted: Settlement completed
  • RJCT — Rejected: Payment failed (check the reason code)
  • PDNG — Pending: Awaiting processing

Step 4: Implement Idempotency

Because network timeouts can cause retried requests, always use a unique endToEndId per transaction. If you retry a request with the same ID, the network will return the original result rather than creating a duplicate payment. This is critical for production reliability.

Testing in Sandbox

The Federal Reserve provides sandbox documentation for FedNow participants. Your institution will give you access to test routing numbers and simulated accounts. Common test scenarios to cover:

  • Successful end-to-end payment (ACSC)
  • Invalid routing number rejection (RJCT)
  • Duplicate payment detection
  • Network timeout and retry handling

Only move to production after all scenarios pass and your institution's compliance team has reviewed your integration.