Bank rails

Instant Payments

11min

Instant payments enable individuals and businesses to transfer funds that clear and settle within seconds between US bank accounts at different US-based financial institutions. Cross River (CR) facilitates instant payments through three networks: CRNow, RTP® via The Clearing House (TCH), and FedNow.
Instant Payments APIs for RTP, FedNow, and CRNow are available in the RTP module of our COS sandbox.
﻿Get started﻿ with Cross River APIs.
This table provides an overview of the Instant Payments APIs, described in detail below.
Action
API Call
Description
﻿Originate a credit transfer﻿ 
POST /v1/payments
Initiates a credit transfer
﻿Originate a request for payment﻿ 
POST /v1/payments/payment-request
Initiates a request for payment
﻿Cancel a request for payment﻿ 
POST /v1/payments/{id}/payment-request/cancel
Initiates a cancellation of a request for payment 
﻿Get instant payment service information for a specific financial institution﻿ 
GET /v1/directory
Retrieves a list of instant payment-related services supported by a specific financial institution
Monetary amounts in API calls and responses are formatted as whole numbers, with no decimal point separating dollars and cents.
Originate a credit transfer
Initiates an instant payment credit transfer
Enables real-time fund transfers from your account to the recipient's account
Transfers can originate from:
Master account
Deposit account (DDA)
Associated subledger
Cross River cannot determine how a receiving financial institution displays payment details to its customers. For information on how fields appear in their banking portal or statements, please contact the receiving FI directly.
Post a payment by ID
POST
Request
Response
Body Parameters
accountNumber
String
required
Account that funds the payment
amount
Integer
required
Dollar amount of transaction in positive integral cents. For example, write $1.00 as 100.
debtor
Object
optional
Debtor Business/Individual Information. Depending on the configuration, this might be populated automatically.
ultimateDebtor
Object
optional
Ultimate debtor business/individual information
creditor
Object
required
Creditor business/individual information
ultimateCreditor
Object
optional
Ultimate creditor business/individual information
purpose
String
optional
Internal CR field used to include a short description of the purpose of the payment. The RDFI does not see this field. 50 characters maximum.
remittanceData
String
optional
A description of the payment, meaning, the remittance advice. Use this field for any remittance information that doesn't have its own field. 140 characters maximum.
remittanceLocation
Object
optional
Remittance location information
clientIdentifier
String
optional
Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes. 50 characters maximum.
queuedPaymentExpiresAt
String
optional
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/Fed.
networkPlatform
String
optional
The payment network platform used to process the payment. Possible values are: TCH (for RTP via The Clearing House), FedNow, or CRNow.
queuedPaymentExpiresAfterInSeconds
Integer
optional
The time interval (in seconds) after which a queued payment will expire if the receiving FI remains offline. This is not sent to TCH or Fed.

If both queuedPaymentExpiresAt and this attribute are provided, this attribute will take precedence.
﻿
Originate a request for payment
Initiates a request for payment (RfP)
Allows the recipient to authorize and trigger an instant payment credit transfer
RfPs can be initiated from:
Master account
Deposit account (DDA)
Associated subledger.
Post a payment request
POST
Request
Response
Body Parameters
accountNumber
String
required
Account from which the RfP is originated
amount
Integer
required
Requested payment amount in positive integral cents. For example, represent $1.00 as 100.
discount
Number
optional
Discount to apply in positive integral cents cents. For example, represent $1.00 as 100.
creditor
Object
optional
Creditor Business/Individual Information. The recipient of the payment, typically the party at CRB initiating the RfP. Depending on the configuration, this information may be populated automatically.
ultimateCreditor
Object
optional
Ultimate Creditor Business/Individual Information. The final recipient of the payment. Depending on the configuration, this information may be populated automatically.
debtor
Object
optional
Debtor Business/Individual Information. The recipient of the RfP who will initiate the credit transfer upon authorization.

For the debtor object, the following fields are required as per RfP business rules:

-debtorName (mandatory)
-At least one additional identifier from the following:
1. [birthCity, birthCountry, birthDate], OR
2. [orgLegalEntityId (LEI)], OR
3. [addressStreetName, addressCity, addressState, addressPostalCode, addressCountry]
ultimateDebtor
Object
optional
Ultimate Debtor Business/Individual Information. The final party receiving the RfP and responsible for initiating the credit transfer upon authorization. 
purpose
String
optional
Internal CR field used to include a short description or purpose for the payment request. The RDFI does not see this field. 50 characters maximum.
remittanceData
String
optional
A description of the payment request, meaning, the remittance advice. Use this field for any remittance information that doesn't have its own field. 140 characters maximum.
remittanceLocation
Object
optional
Remittance location information
clientIdentifier
String
optional
Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes. 50 characters maximum.
requestedExecutionDate
String
required
Date when the payment request needs to be processed by the Debtor. Formatted as yyyy-mm-ddThh:mm:ss[.mmm].
expiryDate
String
required
Expiration date and time of the RfP. If no time is specified, it expires at 12:00 AM on the given date. If a time is provided, it expires within one hour after the specified time on the same date. Formatted as yyyy-mm-ddThh:mm:ss[.mmm].
useCase
String
required
Use one of the following values for the useCase field:

-BusinessToBusiness
-ConsumerBillPay
-AccountToAccount
-DownPaymentOrFinalPayment
-ConsumerToGovernment
industryCategory
String
optional
Use one of the following values for the industryCategory field (optional when useCase is BusinessToBusiness or ConsumerToGovernment):

-HomeUtilities
-TelecomUtilities
-Mortgage
-Rent
-InsurancePremiums
-AutoLoans
-PersonalLoans
-CreditCardPayment
-MediaSubscriptions
-Memberships
-FinancialInstitution
-BrokerOrDealer
-Medical
-OnlineGaming
-RealEstate
-Government
senderID
String
optional
Use the senderId field (optional when useCase is BusinessToBusiness or ConsumerToGovernment), provided by Cross River and generated by The Clearing House (TCH).

Valid senderID's for Sandbox Testing:
-100000000001
-100000000002
-100000000003
-100000000004
-100000000005
﻿
Cancel a request for payment
Cancels a payment request if a credit transfer or payment request response has not been received.
Post a cancel payment request
POST
Request
Response
Path Params
Id
String
required
The payment ID. This first appears in the initial response to canceling a payment request. This ID is in GUID format.
Body Parameters
reasonCode
String
required
Reason code for payment request cancellation. Specifies the justification for the cancellation. Please refer to the Request and Response Codes page for more details.
clientIdentifier
String
optional
A unique identifier assigned to the payment call or COS record. This value reflects the identifier provided in the original request and helps ensure idempotency.
﻿
Refer to Request and response codes﻿ for complete list of values for reason code
Get service info for specific FI (directory)
Retrieves a list of instant payment services supported by a specific financial institution
If the bank supports TCH and FedNow instant payments, service codes for both networks are returned
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
String
optional
The name of the financial institution.
routingNumber
String
optional
The routing number of the specific account at the financial institution receiving the payment, such as the number found on a check
participantId
String
optional
The 11-digit identification number assigned to a participant in the payment network
institutionRoutingNumber
String
optional
The routing number that uniquely identifies the financial institution
networkPlatform
String
optional
The payment network platform used to process the payment. Valid values are:

-TCH – RTP via The Clearing House
-FedNow – Federal Reserve’s instant payment network
﻿
Associated webhooks events
Event Name
Description
Rtp.Payment.Sent
The RTP payment has been successfully transmitted to the receiving institution, and the funds are now available in the receiver's bank account.
Rtp.Payment.Received
An inbound payment has been received from another institution and successfully posted to an account in COS.
Rtp.Payment.Rejected
Payment Rejected – The payment was rejected by the receiving institution or RTP Network.
Insufficient Funds – The payment could not be processed because the originating account had insufficient funds.
Rtp.Payment.Canceled
Partner Cancellation – The payment was canceled at the request of the partner.
Research Cancellation – A payment with a status of ResearchRequired has been canceled.
Rtp.Payment.ResearchRequired
No response was received for the outbound payment. Research is required to determine whether the payment should be completed or canceled.
Rtp.Hold.Escalated
A hold on an outbound payment has been escalated by the Operations team, typically indicating that additional documentation or action is required from the partner.
Rtp.Refund.Requested
A request has been received to refund a previously accepted credit transfer.
Rtp.Payment.Queued
The receiving institution is offline. The payment will be processed once the receiving institution returns online.
Rtp.Limits.Utilization.Changed
This webhook triggers when the percentage of successful transfers reaches 5%, and continues to fire at each 5% increment (e.g., 10%, 15%, etc.).
Rtp.Payment.Expired
This webhook is triggered when an outgoing credit transfer in the queue expires or when a Request for Payment expires due to the absence of a response or incoming credit transfer.
Related topics
﻿Instant Payments at Cross River﻿ 
﻿Instant Payments queuing﻿ 
﻿Instant Payments limits﻿ 
﻿Request and response codes﻿ 
﻿System error codes﻿ 
Tutorials
﻿How to originate an instant payment﻿ 
﻿How to use the RTP directory API﻿ 

Action	API Call	Description
Originate a credit transfer	POST /v1/payments	Initiates a credit transfer
Originate a request for payment	POST /v1/payments/payment-request	Initiates a request for payment
Cancel a request for payment	POST /v1/payments/{id}/payment-request/cancel	Initiates a cancellation of a request for payment
Get instant payment service information for a specific financial institution	GET /v1/directory	Retrieves a list of instant payment-related services supported by a specific financial institution

Event Name	Description
Rtp.Payment.Sent	The RTP payment has been successfully transmitted to the receiving institution, and the funds are now available in the receiver's bank account.
Rtp.Payment.Received	An inbound payment has been received from another institution and successfully posted to an account in COS.
Rtp.Payment.Rejected	Payment Rejected – The payment was rejected by the receiving institution or RTP Network. Insufficient Funds – The payment could not be processed because the originating account had insufficient funds.
Rtp.Payment.Canceled	Partner Cancellation – The payment was canceled at the request of the partner. Research Cancellation – A payment with a status of ResearchRequired has been canceled.
Rtp.Payment.ResearchRequired	No response was received for the outbound payment. Research is required to determine whether the payment should be completed or canceled.
Rtp.Hold.Escalated	A hold on an outbound payment has been escalated by the Operations team, typically indicating that additional documentation or action is required from the partner.
Rtp.Refund.Requested	A request has been received to refund a previously accepted credit transfer.
Rtp.Payment.Queued	The receiving institution is offline. The payment will be processed once the receiving institution returns online.
Rtp.Limits.Utilization.Changed	This webhook triggers when the percentage of successful transfers reaches 5%, and continues to fire at each 5% increment (e.g., 10%, 15%, etc.).
Rtp.Payment.Expired	This webhook is triggered when an outgoing credit transfer in the queue expires or when a Request for Payment expires due to the absence of a response or incoming credit transfer.

Error codes

Limit utilization