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
﻿Originate an instant payment credit transfer﻿ 
POST /v1/payments
Sends a single Instant Payment
﻿Get instant payment service information for a specific financial institution﻿ 
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
﻿Instant Payments at Cross River﻿ 
﻿Instant Payments queuing﻿ 
﻿Instant Payments limits﻿ 
﻿Error codes﻿ 
Tutorials
﻿How to originate an instant payment﻿ 
﻿How to use the RTP directory API﻿ 

Action	API Call	Description
Originate an instant payment credit transfer	POST /v1/payments	Sends a single Instant Payment
Get instant payment service information for a specific financial institution	GET /v1/directory	Returns a list of instant payment-related services that are supported by a specific financial institution

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).

🤔

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.

﻿

Updated 26 Sep 2024

Did this page help you?

Error codes

Request and response codes