> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Receive or send Instant Payments through the FedNow network.

<Warning>
  **Upcoming Change**

  We're updating return-related Instant Payments endpoints to align functionality across FedNow and RTP, including changes to supported return reasons and validation requirements. Partners using return request functionality must update their integrations before the changes are enforced in September 2026.

  👉 [View Details](/upcoming-changes#instant-payments-return-api-updates)
</Warning>

The Federal Reserve developed the FedNow network to enable instant payments between financial institutions in the United States. FedNow operates 24/7/365, requires that funds are transferred from debtors to creditors in 20 seconds or less, and mandates that the receiving financial institution informs creditors of available funds immediately. Lead has a direct connection to the FedNow network and offers a rich experience with the payment rail while abstracting operational complexity.

## Instant Payment Object

The `instant_payment` object describes both incoming and outgoing payments and is organized into three sections: payment details, related messages, and return requests.

### Payment Details

```json theme={null}
{
"id": "instant_payment_xyz123",
"account_id": "account_xyz123",
"account_number_id": "account_number_xyz123",
"created_at": "ISO-8601", 
"updated_at": "ISO-8601", 
"direction": "enum(incoming|outgoing)",
"status": "enum(created|under_review|canceled|rejected|posted)",
"counterparty_status": "enum(under_review|rejected|posted)",
"amount": 5000,
"currency_code": "USD",
"description": "Payment for invoice 12345",
"debtor": {
	"name": "Alex Smith",
	"account number": "1234567890"
},
"debtor_agent": {
	"routing_number": "987654321"
},
"creditor_agent": {
	"routing_number": "987654321"
},
"creditor": {
	"name": "Alex Smith",
	"account_number": "0987654321"
},
"payment_identifiers": {
	"end_to_end_id": "string",
	"uetr": "string",
	"transaction_id": "string"
},
"return": {
	"reason": "enum",
	"details": "string"
},
"rejection": {
	"rejected_by": "enum(lead|network|counterparty)",
	"reason": "enum",
	"details": "string"
},
```

### Related Objects

```json theme={null}
"related_objects": {
	"original_payment_id": "instant_payment_xyz123",
	"return_payment_ids": ["instant_payment_xyz123"]
},
```

### Return Request

```json theme={null}
"return_requests": [{ 
	"created_at": "ISO-8601", 
	"deadline": "ISO-8601",
	"status": "enum(response_needed|pending|rejected|accepted)",
	"reason": "enum",
	"details": "string",
	"resolution": {
		"resolved_at": "ISO-8601",
		"resolved_by": "enum(client|lead|network|counterparty)",
		"rejection_reason": "enum",
		"rejection_details": "string"
}
}]
```