Bank rails

Instant Payments

8min

Instant payments allow individuals and businesses to transmit funds that clear and settle within seconds between US bank accounts at different US-based financial institutions. Cross River (CR) uses both the RTP via TCH and FedNow instant payment networks.

A credit transfer via API call must include at least:

  • The account number funding the transfer
  • The transfer amount
  • The creditor account number and routing number at the receiving bank

Instant Payments APIs are found in the RTP module of our COS sandbox.

@ with Cross River APIs.

This table presents Instant Payments APIs that we describe in detail.

Action

API Call

Description

POST /v1/payments

Sends a single Instant Payment

GET /v1/directory

Returns a list of instant payment-related services that are supported by a specific financial institution

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

Originate a credit transfer

Originates an instant payment credit transfer.

An instant payment credit transfer sends funds from your account to the recipient account in real time. A credit transfer can be sent from a master account, a deposit account (DDA), or an associated subledger.

Cross River cannot know how another financial institution displays to their customers the information transmitted with the Originate a payment message. Contact the receiving FI directly to learn more about fields in their banking portal or on their bank statements.

Post a payment by Id
POST
Request
Response
Body Parameters
accountNumber
required
String
Account that funds the payment
amount
required
Integer
Dollar amount of transaction in positive integral cents. For example, write $1.00 as 100.
debtor
optional
Object
Debtor Business/Individual Information. Depending on configuration this might be populated automatically.
ultimateDebtor
optional
Object
Ultimate Debtor Business/Individual Information
creditor
required
Object
Creditor Business/Individual Information
ultimateCreditor
optional
Object
Ultimate Creditor Business/Individual Information
purpose
optional
String
Internal CR field used to include a short description of purpose of the payment. The RDFI does not see this field. 50 character limit.
remittanceData
optional
String
A description of the payment, meaning, the remittance advice. Use this field for any remittance information that doesn't have its own field. Not more than 140 characters.
remittanceLocation
optional
Object
Remittance location information
clientIdentifier
optional
String
Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.
queuedPaymentExpiresAt
optional
String
Date and time that a queued payment will expire (payment canceled) if the receiving FI is offline, in this format: yyyy-mm-ddThh:mm:ss[.mmm]. Not sent to TCH.
queuedPaymentExpiresAfterInSeconds
optional
Integer
Time interval in seconds after which a queued payment will expire if the receiving FI is offline. Not sent to TCH. If you provide values for both queuedPaymentExpiresAt and this attribute, this attribute takes precedence.


Get service info for specific FI (directory)

Returns a list of instant payment-related services that are supported by a particular financial institution. If the bank supports both TCH and FedNow instant payments, the call returns service codes for each network

For FedNow, an FI must register each RTN separately. An FI can have some but not all RTNs registered for FedNow.

Add query parameters to filter the response the API returns to all GET calls.

Use Pagination to control presentation of your results.

GET
Request
Response
Query Parameters
name
optional
String
Name of financial institution
routingNumber
optional
String
Routing number of the specific account in the financial institution a payment is going to. For example, the number on a check.
participantId
optional
String
11-digit participant ID
institutionRoutingNumber
optional
String
Routing number of the financial institution
networkPlatform
optional
String
The payment network platform used to send the payment. Values are either TCH (for RTP via TCH) or FedNow.


Associated webhooks events

Event Name

Description

Rtp.Payment.Sent

RTP payment has been successfully sent to the receiving institution and the funds are available in the receiver's bank account

Rtp.Payment.Received

Inbound payment has been received from another institution and has successfully posted to an account in COS

Rtp.Payment.Rejected

Payment has been rejected by the receiving institution or RTP Network. The payment originated from an account with insufficient funds.

Rtp.Payment.Canceled

Payment was canceled at the request of the partner or a payment with a status of ResearchRequired has been canceled

Rtp.Payment.ResearchRequired

No response was received for an outbound payment, manual research is required to determine if the payment should be completed or canceled

Rtp.Hold.Escalated

A hold relating to either an outbound payment was marked for escalation by a member of the Operations team. Commonly this is used to indicate additional documentation or action is needed by the partner.

Rtp.Refund.Requested

Request has been received to refund a previously accepted credit transfer

Rtp.Payment.Queued

The receiving institution is offline. The payment will be processed when the receiving institution is back online.

Rtp.Limits.Utilization.Changed

This webhook fires when the percentage of successful transfers hits 5%, and fires again every time the transfer interval goes up 5% (at 5%, 10%, 15% and so on).

Related topics

Tutorials

🤔
Have a question?
Our super-smart AI, knowledgeable support team and an awesome community will get you an answer in a flash.
To ask a question or participate in discussions, you'll need to authenticate first.