---
title: Set payment expiration
slug: tutorials/api/instant-payments/set-payment-expiration
description: Guide setting expiration on payment requests before they’re accepted. Set an expiration time for how long a payment remains in the queue before being cancelled.
docTags: 
createdAt: 2025-01-20T13:04:48.074Z
---

## What you will learn

✅ How to set an expiration time for how long a payment remains in the queue before being cancelled

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. Payments have a default queue expiration of 3 days. If the expiration is reached, Cross River cancels the payment and triggers an `Rtp.Payment.Canceled` webhook.

:::hint{type="info"}
If you are new to instant payments, check out the [instant payments](docId\:U_TnYPQ3-5yepG7jKD5FK) overview.

This tutorial assumes familiarity with APIs. For more information, visit [API basics](docId\:pUTTCwQ5SKLzxYzIn5D1b).
:::

The tutorial uses these API endpoints:

| [POST /rtp/v1/payments](docId:727H0GkQerqHAFKEy67Uu)                                      | Transfers funds between banks in real time via an Instant Payments network                        |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [POST /rtp/v1/payments/{id}/payment-request/cancel](docId\:RIYl47dXZG2Rn5d-APJtr)    | Cancels a payment request if a credit transfer or payment request response has not been received. |

## Before you begin

Make sure you have:

- [API credentials](docId\:wmg-1Fqwq3bj-D3c3HFfs) 
- Your partner ID
- Your master account number
- [Registered](docId\:BN5XtgkJogBe-CtwomCbS) the following webhook events:

| `Rtp.Payment.Queued`   | Payment queued for sending when the receiving financial institution comes back online |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `Rtp.Payment.Canceled` | Payment canceled                                                                      |

## Set queued payment expiration time

To set the expiration time follow the the [send an instant payment](docId:5yRR2S4_i1B34CdzDxR68) tutorial, with the expiration time details set as either a specific date and time or a time in seconds. If both are provided, the system prioritizes the **time in seconds** and ignores the date and time.

:::::WorkflowBlock
::::WorkflowBlockItem
Define an expiration for a specific date and time (`queuedPaymentExpiresAt`)

:::Paragraph{listStyleType="disc" indent="2"}
Use the `queuedPaymentExpiresAt` attribute in your payment request.
:::

:::Paragraph{listStyleType="disc" listStart="2" indent="2"}
Format: **yyyy-mm-ddThh\:mm\:ss** (US Eastern Time).
:::

:::Paragraph{listStyleType="disc" listStart="3" indent="2"}
The value must be a future date and time.
:::

:::Paragraph{listStyleType="disc" listStart="4" indent="2"}
For reference, the sample request includes this attribute on row 17.
:::

:::CodeblockTabs
Sample payment request with date and time expiration queuing

```curl
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"
}
```
:::
::::

::::WorkflowBlockItem
Define an expiration time in seconds (`queuedPaymentExpiresAfterInSeconds`) 

:::Paragraph{listStyleType="disc" indent="2"}
Use the `queuedPaymentExpiresAfterInSeconds` attribute in your payment request.
:::

:::Paragraph{listStyleType="disc" listStart="2" indent="2"}
Enter the value in seconds (whole number).
:::

:::Paragraph{listStyleType="disc" listStart="3" indent="2"}
The countdown starts when the payment is queued.
:::

:::Paragraph{listStyleType="disc" listStart="4" indent="2"}
A value of **0** cancels the payment immediately if the RDFI is offline.
:::

:::Paragraph{listStyleType="disc" listStart="5" indent="2"}
For reference, the sample request includes this attribute on row 17.
:::

:::CodeblockTabs
Sample payment request with queuing expiration in seconds

```curl
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
}
```
:::
::::
:::::

## Cancel a queued payment

Cancel a queued payment anytime using the`POST /v1/payments/{paymentId}/cancel `endpoint.

## Test queuing in sandbox

To simulate offline participants, three participants alternate between online and offline every 60 minutes.

1. Register for the `Rtp.Payment.Queued ` and `Rtp.Payment.Canceled` webhook events.
2. Submit a payment using one of the following routing numbers:
   - **000000010**
   - **000000017**
   - **244084264**
3. If the participant is offline, the `Rtp.Payment.Queued` webhook fires, and the payment status changes to **Queued**.
4. Once the participant returns online, the payment resumes normal processing.

If the payment isn’t queued, continue submitting until the participant cycles offline.