Instant Payment queuing

Participating banks must establish a connection to send and receive instant payments. From time to time, a participating bank is unavailable to transact, either due to routine maintenance or to unknown technical issues that are resolvable with time. When this happens, CR queues (lines up) these Instant Payments submitted to these participating banks.

How it works

Instant payment queuing follows specific steps for how long to wait and how to send the payment if it has been queued.

1. An instant payment is submitted to CR via API.

• Can optionally include a queue expiration date and time, or an expiration deadline in seconds, in the event the payment is queued due to RDFI offline.

• Expiration determines how long a payment waits in queue for the RDFI to go back online before turning to a canceled status.

2. If the receiving institution is offline:

• Payment status changes to Queued and you receive an Rtp.Payment.Queued webhook event.

  Note

  You need to register to receive webhook events.

• The CR system checks payment expiration statuses every 5 minutes. When any payment reaches its expiration time:

  • CR system cancels the payment within 5 minutes of it reaching the expiration time.

  • Payment status changes to Canceled.

  • The Rtp.Payment.Canceled webhook event fires.

• Once the receiving institution is back online, if the payment has not yet expired:

• Payment status changes to Processing:

  Processing status indicates the payment has been sent to the RDFI and we are awaiting a response. Payment can no longer be canceled and must wait for a response from the Instant Payments network.

3. If the receiving institution is online payment flows through as normal.

How long can a payment remain queued?

All payments have a default queue expiration of 3 days. If a payment queue expiration time is reached, CR cancels the payment and you receive a Rtp.Payment.Canceled webhook event.

Can I set my own queue expiration date for a payment?

Yes. You can either set a date and time for payment expiration, or an expiration time in seconds, after which the payment is canceled. If you supply a value for both expiration types, the system applies the expiration time in seconds and ignores the expiration date and time value.

Expiration by date and time

When submitting your payment request, include queuedPaymentExpiresAt, which is a DateTime type attribute and should be entered in this format: yyyy-mm-ddThh:mm:ss[.mmm]. The time should be US Eastern Standard Time.

• queuedPaymentExpiresAt is an optional attribute.

• The value entered must be a future date and time.

In the following sample request the additional field is in row 17.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /v1/payments
{
"accountNumber": "2553179843",
"amount": 15000,
"creditor": {
"routingNumber": "011000138",
"accountNumber": "456789000",
"name": "Cleveland Brown",
"addressStreetName": "Spooner St",
"addressBuildingNumber": "34",
"addressCity": "Quahog",
"addressState": "RI",
"addressPostalCode": "00093",
"addressCountry": "US"
"addressCountry": "US"
},
"queuedPaymentExpiresAt": "2023-02-19T08:22:17.512Z"
}

Expiration by time in seconds

When submitting your payment request, include queuedPaymentExpiresAfterInSeconds, which is an integer type attribute and should be entered in seconds. The system counts the seconds from when the payment is queued.

• queuedPaymentExpiresAfterInSeconds is an optional attribute.

• The value entered must be a whole number.

Use this attribute with a value of 0 instead of configuring your product to automatically cancel a payment when an RDFI is offline. That way you can offer Instant Payment queuing on a payment-by-payment basis.

In the following sample request the additional field is in row 17.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /v1/payments
{
"accountNumber": "2553179843",
"amount": 15000,
"creditor": {
"routingNumber": "011000138",
"accountNumber": "456789000",
"name": "Cleveland Brown",
"addressStreetName": "Spooner St",
"addressBuildingNumber": "34",
"addressCity": "Quahog",
"addressState": "RI",
"addressPostalCode": "00093",
"addressCountry": "US"
"addressCountry": "US"
},
"queuedPaymentExpiresAfterInSeconds": 3600
}

What if I don’t want to wait for queue expiration to be reached?

You can cancel a queued payment at any time via the API: POST /v1/payments/{paymentId}/cancel.

Test in sandbox

To simulate participants going offline, we configured 3 participants to alternate between online and offline status. They alternate status at a minimum of every 60 minutes.

To test queuing:

Register for webhook Rtp.Payment.Queued.

1. Submit payment using any of the following creditor routing numbers:

   • 000000010

   • 000000017

   • 244084264

2. If participant is offline, the Rtp.Payment.Queued webhook fires and the payment status goes to Queued.

   • Once the participant goes online, payment resumes the normal workflow.

3. If payment was not queued, continue to periodically submit payments until participants cycle offline.