Payments

Cancel payment request

Changed on Nov 2, 2026

Cancels an open payment request, so its payment link stops building and sponsoring transactions. Requires payment_requests.manage. Canceling a request that is already canceled returns it unchanged. A paid or expired request returns 409, and so does one whose fee-sponsored transaction can still land: retry once that transaction's blockhash expires. A payer who signed before the cancel can still land the payment; SDP records it as paid, with paidLate set when it landed after the cancel.

post/v1/payments/requests/{paymentRequestId}/cancel

Request

Base URL
http://localhost:8787
URL
http://localhost:8787/v1/payments/requests/{paymentRequestId}/cancel
Auth
HTTP bearer

Path parameters

paymentRequestIdstring required

SDP payment request ID.

Example:preq_example

Headers

x-project-idstring

Required for dashboard sessions. API keys use their assigned project.

Example:prj_example

Idempotency-Keystring

Optional, and honored when sent. 1-255 printable ASCII characters; send a UUID per logical operation and reuse it on every retry. Within 24 hours, a retry with the same key and the same request returns the stored status and body with the response header Idempotent-Replayed: true. Keys are scoped to the credential: within 24 hours, the same key with a different request, or from a different credential, returns 422 IDEMPOTENCY_KEY_REUSED; after that, the same key from a different credential runs as a new request. A rotated API key is a new credential, so after any rotation read the resource with GET to see whether the original request ran, and never resend a money request under the new credential without checking first. A key whose original request is still running returns 409 IDEMPOTENCY_KEY_IN_FLIGHT with Retry-After. A 400, 401, 403, 409 or 429 refusal is not stored, so the same key runs again once the cause is fixed. Access is checked before the key on every request, so a refused request never claims the key, and a credential that has since lost access to the named resource gets 403 instead of the stored response. A replay is a snapshot of the original response: read the current state with GET instead of sending the request again. If the original request never recorded its outcome (it crashed), a same-key retry gets 409 IDEMPOTENCY_KEY_IN_FLIGHT until 15 minutes plus the route's lease have passed since the original was sent (about 16 minutes, or about 20 for transfer batches), then 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN with no Retry-After, as does every later retry with that key: read the resource with GET to see whether it ran, then send again with a new key. After a 5xx, a retry with the same key runs again and answers from the original record instead of acting twice; that answer also carries Idempotent-Replayed: true.

Example:idempotency_example_12345

Response

Payment request canceled

Example response

{
  "data": {
    "id": "preq_example",
    "destinationAddress": "So11111111111111111111111111111111111111112",
    "amount": "100.00",
    "reference": "So11111111111111111111111111111111111111112",
    "status": "canceled",
    "expiresAt": "2025-01-01T00:00:00.000Z",
    "lastCheckedAt": "2025-01-01T00:00:00.000Z",
    "canceledAt": "2025-01-01T00:00:00.000Z",
    "lifecycle": [
      {
        "status": "canceled",
        "at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

Changes

Nov 2, 20269f0b1d561064 Revision changes
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
- warning
  added the new CUSTODY_POLICY_REFUSED enum value to the / response property for the response status
Oct 30, 2026f4a0135eca08 Revision changes
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new RPC_UNAVAILABLE enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new SPONSORED_RENT_OVER_CAP enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_DESTINATION_CHANGED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_NOTHING_TO_RETRY enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RETRY_CLAIMED enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status
- warning
  added the new TRANSFER_BATCH_RUN_EXISTS enum value to the / response property for the response status

Operation history (3 revisions)