Set payment expiration
Cross River queues instant payments to be sent later if for some reason the receiving bank is offline and cannot receive the credit transfer immediately.
In this tutorial, you'll learn how to:
✅ Set an expiration time for how long a payment remains in the queue before being cancelled
If you are new to Instant 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. For more information on sending API calls, see the API overview page.
Make sure you have:
- Your partner ID
- Your master account number
The tutorial uses this API endpoint:
Transfers funds between banks in real time via an Instant Payments network | |
|---|---|
POST /v1/payments/{paymentId}/cancel | |
The tutorial uses these webhooks:
Rtp.Payment.Queued | Payment queued for sending when the receiving financial institution comes back online |
|---|---|
Rtp.Payment.Canceled | Payment canceled |
- 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.
Prepare to send an instant payment as described in the Originate a payment tutorial.
Define your expiration time:
- Set a specific date and time (queuedPaymentExpiresAt)
- Define an expiration time in seconds (queuedPaymentExpiresAfterInSeconds)
If both are provided, the system prioritizes the time in seconds and ignores the date and time.
Payments have a default queue expiration of 3 days.
If the expiration is reached, CR cancels the payment and triggers an Rtp.Payment.Canceled webhook.
- Use the queuedPaymentExpiresAt attribute in your payment request.
- Format: yyyy-mm-ddThh:mm:ss (US Eastern Time).
- The value must be a future date and time.
- This field is optional.
For reference, the sample request includes this attribute on row 17.
- Use the queuedPaymentExpiresAfterInSeconds attribute in your payment request.
- Enter the value in seconds (whole number).
- The countdown starts when the payment is queued.
- A value of 0 cancels the payment immediately if the RDFI is offline.
- This field is optional.
For reference, the sample request includes this attribute on row 17.
Cancel a queued payment anytime using thePOST /v1/payments/{paymentId}/cancel endpoint.
To simulate offline participants, three participants alternate between online and offline every 60 minutes.
- Register for the Rtp.Payment.Queued webhook.
- Submit a payment using one of the following routing numbers:
- 000000010
- 000000017
- 244084264
- If the participant is offline, the Rtp.Payment.Queued webhook fires, and the payment status changes to Queued.
- Once the participant returns online, the payment resumes normal processing.
If the payment isn’t queued, continue submitting until the participant cycles offline.