> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.upwardli.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.upwardli.com/_mcp/server.

# Instant Payments Guide

## Overview

Instant Payments allow you to move funds in real-time from a DDA to an external bank account using RTP (Real-Time Payments). This guide covers how to create, retrieve, and list instant payment requests using the Upward API.

## Prerequisites

* Valid Upward API credentials (Bearer token)
* Active consumer account with a DDA
* Connected external bank account
* Sufficient available balance in the originating account

## Important Constraints

### RTP Participation

The destination bank must be a valid RTP participant. If the receiving bank does not support RTP, you will receive the following error:

```
"Bank is not a valid RTP Participant"
```

### Balance Requirements

* The payment amount must be less than or equal to the available balance in the originating account
* Upward will automatically handle fee removal from the transfer amount
* Ensure sufficient funds are available before initiating a transfer

---

## API Endpoints

### Base URL

```
Production: https://api.upwardli.com
Sandbox: https://api-sandbox.upwardli.com
```

---

## 1. Create Instant Payment

Create a new instant payment request to transfer funds from a DDA to an external bank account.

### Endpoint

```
POST /v2/payments/instant/
```

### Authentication

```
Authorization: Bearer <token>
```

### Request Body

| Parameter                | Type             | Required | Description                               |
| ------------------------ | ---------------- | -------- | ----------------------------------------- |
| `consumer_id`            | string           | Yes      | Unique identifier for the consumer        |
| `originating_account_id` | string           | Yes      | ID of the DDA account to debit            |
| `receiving_account_id`   | string           | Yes      | ID of the external bank account to credit |
| `amount`                 | string (decimal) | Yes      | Payment amount in decimal format          |
| `description`            | string           | No       | Optional description for the payment      |

### Api Reference

[here](/api-access/api-reference/payments/instant/create-create-instant-payment-request)

---

## 2. Retrieve Instant Payment

Get details about a specific instant payment using its external ID.

### Endpoint

```
GET /v2/payments/instant/:external_id/
```

### Authentication

```
Authorization: Bearer <token>
```

### Path Parameters

| Parameter     | Type   | Required | Description                          |
| ------------- | ------ | -------- | ------------------------------------ |
| `external_id` | string | Yes      | The unique ID of the instant payment |

### Api Reference

[here](/api-access/api-reference/payments/instant/retrieve-instant-payment-response)

---

## 3. List Instant Payments

Retrieve a paginated list of all instant payments.

### Endpoint

```
GET /v2/payments/instant/
```

### Authentication

```
Authorization: Bearer <token>
```

### Api Reference

[here](/api-access/api-reference/payments/instant/list-instant-payment-responses)

---

## Webhooks

Upward sends webhook notifications for instant payment events to keep you informed of payment status changes in real-time.

### Webhook Configuration

To receive instant payment webhooks:

Register your webhook endpoint URL with Upward
[here](/concepts/webhooks/event-catalog#ach-payment-webhooks)

---

## Payment Flow

### Typical Instant Payment Flow

1. **Initiate Payment**
   * Client calls `POST /v2/payments/instant/` with payment details
   * API validates RTP participation and available balance
   * Returns payment object with status

2. **Process Payment**
   * Upward deducts amount and fees from originating account
   * Payment is submitted to RTP network
   * Webhook: `Payment.Instant.Created`

3. **Complete Payment**
   * Receiving bank accepts the payment
   * Funds are credited to the external account
   * Webhook: `Payment.Instant.Sent`

### Error Scenarios

**Bank Not RTP Participant**

* Payment request is rejected immediately
* Error returned in API response
* No webhook sent

**Insufficient Balance**

* Payment request is rejected immediately
* Error returned in API response
* No webhook sent

**Network Failure**

* Payment may be queued for retry
* Webhook: `instant_payment.failed`
* Client should monitor payment status