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 we recommend you read the Instant payments overview before starting this tutorial.
The tutorial assumes you have a knowledge of APIs and how they work. Refer to the API overview page for more details.
Make sure you have:
- Your partner ID
- Your master account number
You should be familiar with these terms:
| |
|---|---|
Financial institution (FI) | The bank involved in the transfer of the money between parties |
Debtor | The account sending a payment via the instant payments network |
Creditor | The account receiving a payment via the instant payments network |
The tutorial uses these API endpoints:
| |
|---|---|
Transfer money between banks in real time via the instant payments network |
The tutorial uses these webhooks
| |
|---|---|
Rtp.Payment.Sent | Outbound 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 instant payments network |
To receive the webhook events for this tutorial you need to register each specific webhook event type. Once you're registered, the event objects are sent to the registered URLs.
The event object contains a list of resource identifiers used to download details on each event.
Instant payment credit transfers send funds from your account to the recipient account in real time. Credit transfers can be sent from master accounts and associated subledgers.
The account sending the funds is the debtor and the account receiving the funds is the creditor.
CR offers you two different network platforms for Instant Payments: RTP via The Clearing House (TCH) and FedNow.
In this tutorial, you are the debtor. We are going to originate an outbound credit transfer from your master account to the creditor using an explicit network platform.
The outbound credit transfer can result in the creditor FI:
- Accepting the transfer Send an accepted status back to CR and posted the funds. Status code: ACTC
- Rejecting the transfer Send a rejected status back to CR and no debit/credit occurs. Status code: RJCT
- Does not respond CR receives a reject from the Clearinghouse and no debit/credit occurs. Status code: RJCT
- Accepting the transfer without posting. The credit transfer was accepted but funds were not yet deposited into the creditor account. The creditor FI can subsequently send an accepted status and post the funds into the creditor's account, or send a rejected status, within 24 hours. Status code: ACWP
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.
IMPORTANT We strongly recommend that you include an idempotency key in your request header to provide duplicate protection should the payment fail.
Call POST /rtp/v1/payments. For this call, some attributes are required. A full list of attributes is found here.
In our tutorial, you will send a gift of $175 to C Brown.
Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.
A successful API call returns a JSON response with the details of your originated credit transfer.
When the credit transfer (pacs.008) is sent to the instant payments network, the Rtp.Payment.Sent webhook event fires. This event contains the payment ID within the details section of the event body (in this case, 7b5f4bfb-8595-452b-914e-ad9400f7b8e3).
The Rtp.Payment.Sent and Rtp.Payment.Received webhook events tell you the status of your credit transfer.
You can simulate receiving a reject response from a creditor.
Call POST /rtp/v1/payments like you did in Originate the credit transfer.
Add the reject: prefix to the creditor name like you see on line 9 in the request example.
The response example returns a payment status of Rejected on line 13.
The Rtp.Payment.Rejected event is triggered.
The details object in the Rtp.Payment.Rejected event contains the payment ID from the response body (id). In this case: 7b5f4bfb-8595-452b-914e-ad9400f7b8e3.
In the details object of the event, the resultCode gives you the reason code, in this case AC06 (Account is blocked).
