--- title: "Cancel payment request" method: POST path: "/payment-requests/{paymentRequestId}/cancel" tags: ["PaymentRequests"] --- # Cancel payment request `POST /payment-requests/{paymentRequestId}/cancel` Cancel an open outgoing payment request ## Path parameters - `paymentRequestId` string, required — Payment request ID (prq_*). ## Headers - `Idempotency-Key` string, required - `X-Instance-ID` string, nullable ## Response `200` Successful Response - object - `data` object, required - `type` 'paymentRequest', required — Resource type. Always `paymentRequest`. - `id` string, required — Payment request ID (prq_*). - `attributes` object, required - `amount` integer, required — Amount in cents. - `currency` string, required — Currency code. - `status` 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'CANCELED' | 'DECLINED' | 'EXPIRED', required — Payment request status. - `payerCanPay` boolean, required — Whether the payer can still fulfill this request: it is OPEN, unexpired, and has no payment attempt. Does not check the payer's authorization or funding. - `payerCanDecline` boolean, required — Whether the payer can still decline this request: it is OPEN. Does not check the payer's authorization. - `description` string, nullable, required — Free-form description provided at creation. Maximum 80 characters. - `tags` object, required — Metadata visible to anyone who can read the resource. - `requesterName` string, nullable, required — Display name of the party requesting payment. - `requesterEmail` string, nullable, required — Email of the party requesting payment. - `requesterAvatarUrl` string, uri, nullable, required — Public avatar URL for the party requesting payment, if one is set. - `requesterHandle` string, nullable, required — The requesting party's composed public handle (@namespace), or null when it has none. - `walletName` string, nullable, required — Receiving wallet name, or null when unnamed or hidden from the caller. - `payerName` string, nullable, required — Display name of the payer. - `payerEmail` string, nullable, required — Email of the payer, or null when none is known. - `payerAvatarUrl` string, uri, nullable, required — Public avatar URL for the payer party, if one is set. - `payerHandle` string, nullable, required — The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less. - `payerPhone` string, nullable, required — Payer phone number when addressed by phone. - `payerPartyId` string, nullable, required — Natural party ID (pty_*) resolved for the payer, including agent owner parties. - `payerIdentifierType` 'email' | 'phone' | 'party_id' | 'agent_id' | 'handle', required — Identifier type used to address the payer. - `payerIdentifier` string, required — Identifier value used to address the payer. - `initiatorParty` object, nullable, required — The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party. - `id` string, required — Party ID (pty_*). - `name` string, required — Party display name. - `handle` string, nullable, required — Party handle, such as @acme, or null when none is set. - `initiatorAgent` object, nullable, required — Agent that created this payment request, when one did. Otherwise null. - `id` string, required — Agent ID (agt_*). - `name` string, required — Agent display name. - `handle` string, nullable, required — Agent handle, such as @acme-support, or null when none is set. - `paymentLinkUrl` string, uri, required — URL the payer visits to complete payment. - `transactionId` string, nullable, required — Transaction (txn_*) created by the most recent payment attempt, or null when none has been made. - `createdAt` string, required — RFC 3339 timestamp when the payment request was created. - `updatedAt` string, required — RFC 3339 timestamp when the payment request was last updated. - `relationships` object, required - `requesterParty` object, required — Party requesting the payment. - `data` object, required — Related resource identifier. - `type` 'party', required — Resource type. Always `party`. - `id` string, required - `wallet` object, required — Wallet that receives the funds. - `data` object, required — Related resource identifier. - `type` 'wallet', required — Resource type. Always `wallet`. - `id` string, required - `payerParty` object, required — Resolved payer party, if the payer is known to Natural. - `data` object, nullable, required — Related resource identifier. - `type` 'party', required — Resource type. Always `party`. - `id` string, required - `payerAgent` object, required — Payer agent, or null unless addressed by agent ID or agent handle. - `data` object, nullable, required — Related resource identifier. - `type` 'agent', required — Resource type. Always `agent`. - `id` string, required - `payment` object, required — Payment submitted for this payment request, if one exists. - `data` object, nullable, required — Related resource identifier. - `type` 'payment', required — Resource type. Always `payment`. - `id` string, required ## Other responses - `400` — Validation Error - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. - `409` — Conflict - `422` — Validation Error. The response contains one error object for each invalid request value. - `428` — Precondition Required - `429` — Too Many Requests - `500` — Internal Server Error - `501` — Not Implemented - `502` — Bad Gateway - `503` — Service Unavailable ## Changes - **2026-09-02** `c7c12da5915f` — 12 info - added the optional property `errors/items/meta/limitScope` to the response with the `400` status - added the optional property `errors/items/meta/limitScope` to the response with the `401` status - added the optional property `errors/items/meta/limitScope` to the response with the `403` status - added the optional property `errors/items/meta/limitScope` to the response with the `404` status - …8 more - **2026-08-27** `359d267dca88` — 1 info - deleted the `header` request parameter `X-Agent-ID` with deprecation - **2026-08-23** `b1ad79e918ac` — 1 info - `header` request parameter `X-Agent-ID` was deprecated - **2026-08-13** `ba1fb54c5939` — 1 info - added the required property `data/attributes/tags` to the response with the `200` status - **2026-07-26** `270e233e401c` — 1 breaking, 1 warning, 8 info - the `data/attributes/description/anyOf[subschema #1]/` response property's maxLength was unset from `500` for the response status `200` - for the `header` request parameter `Idempotency-Key`, the maxLength was set to `255` - added the required property `data/attributes/initiatorAgent` to the response with the `200` status - added the required property `data/attributes/initiatorParty` to the response with the `200` status - …6 more [Full history](https://skmtc.dev/natural/apis/natural-api/changes/payment-requests/:paymentRequestId/cancel/post.md) --- [API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/1132c9ddb7bd?raw)