Cancel payment
PaymentsAPI REFERENCE
Cancel payment
POST
/v1/payments/{paymentId}/cancelCancel a payment that has not yet completed. It stops accepting funds and moves to a terminal Failed state. Only valid from early statuses (before finality).
Example request
A minimal request you can copy and run.
curl -X POST https://api.suward.com/v1/payments/<payment_id>/cancel \ -H "X-Api-Key: $SUWARD_API_KEY"Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| paymentId | string | yes | Payment ID |
Response
| Name | Type | Required | Description |
|---|---|---|---|
| acceptedAt | integer | no | Unix-milliseconds timestamp when the payment reached the accepted state (safe confirmations, balance credited). Null before acceptance. |
| activatedAt | integer | no | Unix-milliseconds timestamp when the payment was activated and its payment window began counting. Null before activation. |
| activationFlowSeconds | integer | no | Resolved activation grace period, in seconds. Null when not configured. |
| address | string | no | On-chain deposit address the customer must send funds to. Null until the payment is activated and an address is assigned. |
| amount | string | no | Integer string in the asset's smallest unit. |
| amountConfirmed | string | no | Integer string in the asset's smallest unit. |
| amountReceived | string | no | Integer string in the asset's smallest unit. |
| asset | no | Asset the payment is denominated in, as an asset id-string (see GET /v1/assets). Null until an asset is selected for the payment. | |
| confirmedAt | integer | no | Unix-milliseconds timestamp when the payment reached finalization (confirmed). Null until confirmed; may revert if a chain reorg undoes the confirmation. |
| createdAt | integer | no | Unix-milliseconds timestamp when the payment was created. |
| expiresAt | integer | no | Unix-milliseconds timestamp when the payment window closes; the payment expires (fails) if it has not been paid by then. |
| externalId | string | no | Merchant's own identifier for this payment, echoed from creation. Null when none was provided. |
| fee | string | no | Platform fee: 0.4% of the amount, minimum $1 equivalent. Integer string in the asset's smallest unit. |
| id | string | no | Unique Suward identifier of the payment. Use it in the payment endpoints (get, cancel, transactions) and as the checkout page path. |
| metadata | object | no | Arbitrary key/value data attached by the merchant at creation, echoed back unchanged. |
| networkFee | string | no | Estimated on-chain (gas) cost, deducted from the received amount. Integer string in the asset's smallest unit. |
| quotedPrice | string | no | USD price of the asset locked at creation, decimal string. Fees are computed from this price at settlement, so the merchant's net is deterministic. |
| networkFeePayer | no | Who bears the network (gas) fee, echoed from creation. | |
| serviceFeePayer | no | Who bears the platform (service) fee, echoed from creation. | |
| paymentWindowSeconds | integer | no | Resolved length of the payment window, in seconds. |
| projectId | string | no | Identifier of the project that owns this payment. |
| redirectConfig | no | Return-to-store redirect configuration echoed from creation. Null when none was configured. | |
| status | no | Main payment lifecycle status. See the status enum for the full meaning of each value. | |
| subStatus | no | Fine-grained payment sub-status describing the current step or amount condition. See the sub-status enum for the full meaning of each value. | |
| transactions | no | Preview page of the on-chain transactions detected for this payment (newest first). Use GET /v1/payments/{paymentId}/transactions for the full paginated list. | |
| underpaymentTolerance | string | no | Integer string in the asset's smallest unit. |
| updatedAt | integer | no | Unix-milliseconds timestamp when the payment was last updated. |
| webhookUrl | string | no | Webhook URL that receives this payment's events, echoed from creation. Null when the project default webhook is used. |
| paymentPageUrl | string | no | Absolute URL of the Suward-hosted checkout page where the customer pays this payment. |
Response · JSON
{ "acceptedAt": 0, "activatedAt": 0, "activationFlowSeconds": 3600, "address": "0xabc…def", "amount": "100000000", "amountConfirmed": "100000000", "amountReceived": "100000000", "asset": "USDT_ETHEREUM", "confirmedAt": 0, "createdAt": 0, "expiresAt": 0, "externalId": "order_abc123", "fee": "1000000", "id": "obj_abc123", "metadata": {}, "networkFee": "150000", "quotedPrice": "string", "networkFeePayer": "merchant", "serviceFeePayer": "merchant", "paymentWindowSeconds": 3600, "projectId": "obj_abc123", "redirectConfig": {}, "status": "pending", "subStatus": "created", "transactions": {}, "underpaymentTolerance": "0", "updatedAt": 0, "webhookUrl": "https://example.com/webhook", "paymentPageUrl": "string"}