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

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