Real-time payments #

The RTP® Network is a payments system that was launched by The Clearing House in 2017 as the newest payment rail in the U.S. since the advent of the ACH Network. Payment speed and availability are the primary benefits of utilizing the RTP® Network, as businesses can send and receive payments to eligible bank accounts 24/7/365. In addition, RTP transfers come with other favorable characteristics, such as greater transparency of payment status that provides confirmation of funds availability to the end user sending or receiving a payment.

The core of the Dwolla Platform was built around a simplified connection to the U.S. banking infrastructure for businesses to easily initiate digital payments via the ACH Network. As the Dwolla Platform evolves, RTP adds a new processing channel for businesses, providing flexible payment capabilities to build within their own applications.

While RTP and ACH are similar in many ways, there are some key differences:

ACHRTP
Sent via the ACH Network operators (either the Federal Reserve Bank or The Clearing House).Sent via the RTP® Network operator, The Clearing House.
Rules and regulations issued by National Automated Clearing House Association (Nacha).Rules and regulations issued by The Clearing House (TCH).
Funds can take 1-3 days to be available.Funds made available within seconds.
Agreed-upon processes for correcting erroneous transactions (i.e. reversal requests).Funds are irrevocable once sent (although not guaranteed or required, a request for return of funds may be issued).

Use cases and characteristics #

The RTP® Network supports credit “push” transfers, whereas ACH supports credit push as well as debit pull transfers. RTP is particularly suited to support disbursement use cases. Whether your business is built around B2B, B2C or a combination, you can power your application with RTP.

  • Balance Funded Transfers - The RTP® Network is a good funds model, and to initiate transfers through the Dwolla Platform, funds must be available in the sender’s Dwolla balance.
  • Credit Sends Only - RTP transactions are all credits. The RTP® Network does include “Requests for Payment,” but only a very small number of financial institutions support this, and it still relies on a credit to be initiated by the payer upon receiving the request. As adoption of Request for Payment increases among businesses, we expect more FIs will support this feature.
  • RTP Enabled Financial Institutions - More than 56% of FIs support RTP, with adoption growing at an aggressive pace.

Identifying an RTP-enabled Funding Source #

On the Dwolla Platform, Funding Sources allow bank accounts to be added or retrieved. Available for both a Dwolla Master Account and Customers (end users) resources, funding sources have represented payment accounts used for ACH, Wire, and/or Push-to-Debit activities. Dwolla will be able to identify a bank account as RTP-enabled upon creation of a Funding Source, so no additional information is needed from your end users or application.

Retrieving an RTP-enabled Funding Source

When retrieving an existing Funding Source resource from the API, the response will contain a “channels” attribute which represents the different capabilities available for transfers. For a bank account, historically the only values available have been “ach” and “wire”. The example below represents how “real-time-payments” is returned within the “channels” array to identify an RTP-eligible account.

json
"channels": [
  "ach",
  "real-time-payments"
]

Initiating an RTP credit transfer #

In order to initiate a transfer with RTP processing, an optional processingChannel JSON object must be included in the transfer request. The processingChannel object contains the destination key with a value of real-time-payments. This processingChannel object will be returned when retrieving the transfer from the API. Specifying the destination processingChannel with real-time-payments will require a permission to be enabled.

An optional rtpDetails object can be included in the transfer request body. This allows additional information to be passed to the payment recipient's bank account about their RTP credit transfer.

Check out our guide to learn how you can simulate an RTP transfer in Sandbox.

The following example assumes the sending party has funds pre-loaded to their balance Funding Source and that the destination party has a bank account connected that is RTP-enabled.

JavaScript
var requestBody = {
  _links: {
    source: {
      href: "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
    },
    destination: {
      href: "https://api-sandbox.dwolla.com/funding-sources/ecf993e2-fa22-4cea-8022-c7861200288f",
    },
  },
  amount: {
    currency: "USD",
    value: "10000.00",
  },
  processingChannel: {
    destination: "real-time-payments",
  },
  rtpDetails: {
    destination: {
      remittanceData: "ABC_123 Remittance Data",
    },
  },
};

dwolla
  .post("transfers", requestBody)
  .then((res) => res.headers.get("location")); // => 'https://api.dwolla.com/transfers/636de847-7d02-e711-80ee-0aa34a9b2388'

Retrieving an RTP credit transfer #

When retrieving the transfer from the API, the response will contain an rtpDetails object. Within the rtpDetails object will be a destination JSON object that includes a remittanceData key-value pair, depending on if it was included in the original RTP transfer request, and a networkId key-value pair.

The networkId is a unique identifier for an RTP credit transfer which is passed in the payment request to the recipient's bank. It appears on the transfer API resource once the credit entry clears into the destination bank account.

Request and response #

JavaScript
var transferUrl =
  "https://api.dwolla.com/transfers/243fd252-3fcf-eb11-8134-d050ab358a03";

dwolla.get(transferUrl).then(function (res) {
  res.body.status; // => 'processed'
});

Webhook notifications #

Webhooks notification events will be processed in the same sequence as an ACH transfer. The primary difference is that once the transfer is created, the completion or failure events will be triggered moments later rather than days. The specific events include -

Event TopicDescription
customer_bank_transfer_createdSent when the RTP transfer is created
customer_bank_transfer_failedSent if the RTP transfer fails*
customer_bank_transfer_completedSent if the RTP transfer is completed successfully
customer_funding_source_rtp_enabledSent when a funding source is identified as RTP eligible
customer_funding_source_rtp_disabledSent when an RTP eligible funding source is later identified as RTP ineligible

*Based on responses from TCH and Cross River Bank, we will provide more descriptive failure reasons.

Error Codes #

Error codes provide the reason a message did not complete and can be found on the payment Result.Code. The Result.Code will be OK if the payment was successfully sent/received.

CodeDescription
650Cannot parse the message
690Signature mismatch or verification error
BLKDPayment has been blocked
AC02Debtor account is invalid
AC03Creditor account is invalid
AC04Account closed
AC06Account is blocked
AC07Creditor account closed
AC10Debtor account currency is invalid or missing
AC11Creditor account currency is invalid or missing
AC13Debtor account type missing or invalid
AC14Creditor account type missing or invalid
AG01Transaction is forbidden on this type of account
AG03Transaction type is not supported/authorized on this account
AGNTIncorrect Agent
AM02Specific transaction/message amount is greater than allowed maximum
AM04Amount of funds available to cover specified message amount is insufficient
AM09Amount received is not the amount agreed or expected
AM11Transaction currency is invalid or missing
AM12Amount is invalid or missing
AM13Transaction amount exceeds limits set by clearing system
AM14Transaction amount exceeds limits agreed between bank and client
BE04Specification of creditor's address, which is required for payment, is missing/not correct
BE06End customer specified is not known at associated Sort/National Bank Code or no longer exists in the books
BE07Specification of debtor's address, which is required for payment, is missing/not correct
BE10Debtor country code is missing or invalid
BE11Creditor country code is missing or invalid
BE13Country code of debtor's residence is missing or invalid
BE14Country code of creditor's residence is missing or invalid
BE16Debtor identification code missing or invalid
BE17Creditor identification code missing or invalid
DS24Waiting time expired due to incomplete order
DT04Future date is not supported
DUPLPayment is a duplicate of another payment
DS0HSigner is not allowed to sign for this account
FF02Syntax error reason is provided as narrative information in the additional reason information
FF03Invalid Payment Type Information
FF08End to End ID is missing or invalid
MD07End customer is deceased
NARRReason is provided as narrative information in the additional reason information
RC01Bank identifier code specified in the message has an incorrect format
RC02Bank identified is invalid or missing
RC03Debtor FI identifier is invalid or missing
RC04Creditor FI identifier is invalid or missing
TM01Invalid Cut Off Time
TK01Invalid Token
TK02Sender Token Not Found
TK03Receiver Token Not Found
TK04Token Expired
TK05Token Found with Counterparty Mismatch
TK06Token Found with Value Limit Rule Violation
TK07Single Use Token Already Used
TK08Token Suspended
NOATReceiving Customer Account does not support/accept this message type
OKCompleted
1100Any Other Reasons Reason is provided as narrative in the additional information
9909Central Switch (RTP) system malfunction
9910Instructed Agent signed-off
9912Recipient connection is not available
9934Instructing Agent signed-off
9946Instructing Agent suspended
9947Instructed Agent suspended
9948Central Switch (RTP) service is suspended

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys
2022 All Rights Reserved
Financial institutions play an important role in our network.

All funds transfers made using the Dwolla Platform are performed by a financial institution partner, and any funds held in a Dwolla Balance are held by a financial institution partner. Learn more about our financial institution partners.