Originate a payment
In this tutorial, you'll learn how to
✅ Originate a real-time payment credit transfer from your master account.
✅ Simulate a rejected credit transfer.
If you are new to real-time payments, check out the Instant Payments overview.
This tutorial assumes familiarity with APIs. For more information, visit the API overview page.
Make sure you have:
- Your partner ID
- Your master account number
You should be familiar with these terms:
Financial institution (FI) | The bank or credit union facilitating the transfer of funds between parties |
|---|---|
Debtor | The account initiating and sending a payment through the Instant Payments network |
Creditor | The account receiving funds through the Instant Payments network |
API endpoints used in this tutorial:
Transfers funds between banks in real time via an Instant Payments network |
|---|
Webhooks used in this tutorial:
Rtp.Payment.Sent | Payment successfully sent to the receiving institution; funds are available in the recipient’s account |
|---|---|
Rtp.Payment.Received | Payment received and posted to an account in COS |
Rtp.Payment.Rejected | Payment rejected by the receiving institution or Instant Payments network. |
- To receive webhook events, register for each webhook event type. Events are sent to the URLs you register.
- The event object includes resource identifiers that provide details on each event.
Instant payment credit transfers allow funds to move from your account to the recipient's account in real time. Transfers can originate from master accounts or subledgers.
- The debtor sends the payment, and the creditor receives it.
- Cross River supports three network platforms:
- RTP® via The Clearing House (TCH)
- FedNow®
- CRNow
In this tutorial, you are the debtor. You will send an outbound credit transfer from your master account to the creditor using a specified network platform.
Possible Outcomes:
- Accepted Transfer: Funds are posted to the recipient’s account.
- Status: ACTC (Accepted)
- Rejected Transfer: Payment is rejected by the creditor FI or the network. No funds are transferred.
- Status: RJCT (Rejected)
- No Response: The transfer times out, resulting in rejection.
- Status: RJCT (Rejected)
- Accepted Without Posting: The payment is accepted but funds are not immediately posted. The creditor FI can accept or reject the transfer within 24 hours.
- Status: ACWP (Accepted Without Posting)
Cross River cannot confirm how the receiving FI displays payment details. Contact the recipient FI directly for specifics on how the payment will appear.
IMPORTANT We strongly recommend that you include an idempotency key in the request header to prevent duplicate payments in case of a failure.
- Use POST /rtp/v1/payments to initiate a credit transfer.
- In this tutorial, you will send $175 to C. Brown.
Amounts in API calls and responses are written without decimal points (e.g., $175 is written as 17500).
A successful API call returns a JSON response containing the details of the originated credit transfer.
When a credit transfer (pacs.008) is sent to the instant payments network, the Rtp.Payment.Sent webhook fires. The event body includes the payment ID in the details section (e.g., 7b5f4bfb-8595-452b-914e-ad9400f7b8e3).
- Rtp.Payment.Sent – Confirms the payment was sent.
- Rtp.Payment.Received – Confirms the payment was received and posted.
These webhooks provide real-time updates on the status of your credit transfer.
You can simulate a rejected response from the creditor:
- Call POST /rtp/v1/payments (same as initiating a credit transfer).
- Add reject: before the creditor’s name (see line 9 in the request example).
The response example shows a status of Rejected on line 13.
The Rtp.Payment.Rejected event is triggered when a credit transfer is rejected.
- The details object in the event contains the payment ID from the response body (e.g., 7b5f4bfb-8595-452b-914e-ad9400f7b8e3).
- The resultCode in the details object provides the rejection reason.
- Example: AC06 – Account is blocked.