Cancel a payment intent

Cancel an intent that has not been paid (requires_payment_method or requires_action).

POST/v1/payment_intents/{id}/cancelscope payments:write

Nothing is charged afterwards. An intent whose settlement was already sent (or whose payer already confirmed) cannot be canceled: refund it instead. Canceling a canceled intent returns it unchanged.

Path parameters

idstringrequired: Payment intent ID (pi_…).

Headers

ZyloPay-Versionstring: Pin the request to an API version (2026-09-28). Defaults to the version the API key was created with.
Idempotency-Keystring: Recommended. A unique key per operation (a UUID v4); retries with the same key and body return the first response.

Returns

HTTP 200 with the payment intent object.

Errors

Status	Meaning
`400`	Invalid request (`invalid_request_error` / `idempotency_error`).
`401`	Missing, invalid, expired or revoked API key (`authentication_error`).
`403`	The key lacks the scope, the IP is not allowed, or the account is disabled (`permission_error`).
`409`	Conflict: idempotency key reused or in progress, or the object is in the wrong state.
`429`	Rate limit reached for this key (`rate_limit_error`); see `Retry-After`.
`500`	Internal error (`api_error`). Retry with the same `Idempotency-Key`.

Branch on error.code. Every code is listed in error codes.

Example request

curl https://zylopay-api.fly.dev/api/v1/payment_intents/pi_3f2c9e1a7b6d4c0e9f8a1b2c3d4e5f60/cancel \
  -X POST \
  -H "Authorization: Bearer $ZYLOPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Example response

{
  "id": "pi_3f2c9e1a7b6d4c0e9f8a1b2c3d4e5f60",
  "object": "payment_intent",
  "livemode": false,
  "amount": 2500000,
  "currency": "usdc",
  "status": "canceled",
  "terminal": "tml_ZP-4821-K",
  "order_id": "A7K2Q9XZ",
  "description": "Table 12",
  "metadata": {
    "pos_order": "48213"
  },
  "source": "api",
  "payment": null,
  "tx_hash": null,
  "next_action": null,
  "last_payment_error": null,
  "cancellation_reason": "requested_by_merchant",
  "canceled_at": "2026-09-28T14:02:52.000Z",
  "network": "testnet",
  "expires_at": "2026-09-28T14:04:11.000Z",
  "created": "2026-09-28T14:02:11.000Z"
}

Cancel a payment intent

Path parametersCopy Anchor Link

HeadersCopy Anchor Link

ReturnsCopy Anchor Link

ErrorsCopy Anchor Link

Example requestCopy Anchor Link