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

ParameterTypeRequiredDescription
consumer_idstringYesUnique identifier for the consumer
originating_account_idstringYesID of the DDA account to debit
receiving_account_idstringYesID of the external bank account to credit
amountstring (decimal)YesPayment amount in decimal format
descriptionstringNoOptional description for the payment

Api Reference

here

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

ParameterTypeRequiredDescription
external_idstringYesThe unique ID of the instant payment

Api Reference

here

3. List Instant Payments

Retrieve a paginated list of all instant payments.

Endpoint

GET /v2/payments/instant/

Authentication

Authorization: Bearer <token>

Api Reference

here

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

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