Bank rails

Instant Payments

12min

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.

Requirements for Credit Transfers via API

To initiate a credit transfer via API, you must have the following information:

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

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 an instant payment credit transfer

POST /v1/payments

Initiates a single Instant Payment

Originate a request for a credit transfer

POST /v1/payments/payment-request

Initiates a request for a single Instant Payment

Cancel a request for a credit transfer

POST /v1/payments/{id}/payment-request/cancel

Initiate a cancellation of a requested 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
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 the 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 the purpose of the payment. The RDFI does not see this field. 50 characters maximum.
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. 140 characters maximum.
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. 50 characters maximum.
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/Fed.
networkPlatform
optional
String
The payment network platform used to process the payment. Possible values are: TCH (for RTP via The Clearing House), FedNow, or CRNow.
queuedPaymentExpiresAfterInSeconds
optional
Integer
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 payment-request

  • 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
required
String
Account from which the RfP is originated
amount
required
Integer
Requested payment amount in positive integeral cents. For example, represent $1.00 as 100.
purpose
optional
String
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
optional
String
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
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. 50 characters maximum.
requestedExecutionDate
required
String
Date when the payment request needs to be processed by the Debtor. Formatted as yyyy-mm-ddThh:mm:ss[.mmm].
expiryDate
required
String
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].
debtor
optional
Object
Debtor Business/Individual Information. The recipient of the RfP who will initiate the credit transfer upon authorization. Depending on the configuration, this information may be populated automatically.
ultimateDebtor
optional
Object
Ultimate Debtor Business/Individual Information. The final party receiving the RfP and responsible for initiating the credit transfer upon authorization.
creditor
optional
Object
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
optional
Object
Ultimate Creditor Business/Individual Information. The final recipient of the payment. Depending on the configuration, this information may be populated automatically.


Cancel a payment-request

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
required
String
The payment ID. This first appears in the initial response to canceling a payment request. This ID is in GUID format.
Body Parameters
reasonCode
required
String
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
optional
String
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
optional
String
The name of the financial institution.
routingNumber
optional
String
The routing number of the specific account at the financial institution receiving the payment, such as the number found on a check
participantId
optional
String
The 11-digit identification number assigned to a participant in the payment network
institutionRoutingNumber
optional
String
The routing number that uniquely identifies the financial institution
networkPlatform
optional
String
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.).

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

Updated 05 Feb 2025
Did this page help you?
PREVIOUS
Error codes
NEXT
Limit utilization
Docs powered by Archbee