--- title: "Decline payment request as test payer" method: POST path: "/simulations/payment-requests/{paymentRequestId}/decline" tags: ["Simulations"] --- # Decline payment request as test payer `POST /simulations/payment-requests/{paymentRequestId}/decline` Decline an open payment request addressed to your test payer ## 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. - `fee` object, nullable, required — Fee deducted from your proceeds as the recipient. Null when no fee applies, the fee was voided, or your party is not the fee payer. - `amount` integer, required — Fee amount in cents. - `currency` 'USD', required — Currency of the fee. - `payer` 'recipient', required — Party role charged the fee. - `applied` 'deducted', required — The fee is subtracted from the principal amount before the recipient receives it. - `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. - `expiresAt` string, nullable, required — RFC 3339 timestamp when this payment request expires, or null when it does not expire. - `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-25** `b61b8441fba4` — 1 info - added the required property `data/attributes/expiresAt` to the response with the `200` status - **2026-09-23** `bcf3b028c3e5` — 1 info - added the required property `data/attributes/fee` to the response with the `200` status - **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 [Full history](https://skmtc.dev/natural/apis/natural-api/changes/simulations/payment-requests/:paymentRequestId/decline/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/ca3882d75a00?raw)