Cancellation conflicts - Hosted checkout

TL;DR: Cancel only works on a pending session — check the status first if you get a 409.

Cancelling a checkout session only makes sense while it’s still pending. Calling cancel on a session in any other state returns a conflict, rather than silently doing nothing or charging/refunding on your behalf.

When this happens

You call cancel while the shopper is mid-payment (session processing), or after it already reached completed, failed, expired, or cancelled.
You call cancel on a checkout_id that doesn’t exist for your account.

What you see

Situation	HTTP status	Error type
Session is `pending`	`200`	— cancelled successfully
Session is already `cancelled`	`200`	— idempotent; returns the same result, no error
Session is `processing` or any other non-`pending` state	`409`	`session:invalid_state`
Session doesn’t exist, or belongs to a different account	`404`	`session:not_found` — identical response either way
`checkout_id` or API key is malformed	`404`	`resource:not_found`

Calling cancel twice on an already-cancelled session is safe — it’s treated as idempotent, not an error. Only a session in processing or a terminal state (completed, failed, expired) other than cancelled returns the 409.

What to do

Check the session's current status first

Before retrying a cancel that returned 409, find out what actually happened (API reference):

#!/usr/bin/env bash
# Authenticated merchant view of a checkout session. Branch on data.status;
# never on gateway_response_code. Note: GET timestamps are epoch
# milliseconds, unlike the ISO string returned at create time.
set -euo pipefail

CHECKOUT_BASE="${RADIUMONE_CHECKOUT_BASE:-https://checkout-sandbox.radiumone.io}"
: "${RADIUMONE_SECRET_KEY:?set RADIUMONE_SECRET_KEY to your r1sk_* secret key}"
: "${RADIUMONE_CHECKOUT_ID:?set RADIUMONE_CHECKOUT_ID to the checkout_id to verify}"

curl -sS "$CHECKOUT_BASE/api/v1/checkout/sessions/$RADIUMONE_CHECKOUT_ID" \
  -H "X-Api-Key: $RADIUMONE_SECRET_KEY"

#!/usr/bin/env node
// Authenticated merchant view of a checkout session. Branch on data.status;
// never on gateway_response_code. Node 18+ ESM fetch.
// Env: RADIUMONE_SECRET_KEY, RADIUMONE_CHECKOUT_ID, RADIUMONE_CHECKOUT_BASE.
const CHECKOUT_BASE = process.env.RADIUMONE_CHECKOUT_BASE || "https://checkout-sandbox.radiumone.io";
const secretKey = process.env.RADIUMONE_SECRET_KEY;
const checkoutId = process.env.RADIUMONE_CHECKOUT_ID;

async function retrieveCheckoutSession() {
  const res = await fetch(`${CHECKOUT_BASE}/api/v1/checkout/sessions/${checkoutId}`, {
    headers: { "X-Api-Key": secretKey },
  });
  const payload = await res.json();
  if (!res.ok) {
    throw new Error(`checkout session fetch failed: ${payload.code ?? payload.type} (${res.status})`);
  }
  // Confirm order_reference and amount match your order before fulfilling.
  return payload;
}

retrieveCheckoutSession().then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Authenticated merchant view of a checkout session. Branch on ``status``;
never on ``gateway_response_code``.
"""
import json
import os

import requests

CHECKOUT_BASE = os.environ.get("RADIUMONE_CHECKOUT_BASE", "https://checkout-sandbox.radiumone.io")


def retrieve_checkout_session() -> dict:
    checkout_id = os.environ["RADIUMONE_CHECKOUT_ID"]
    resp = requests.get(
        f"{CHECKOUT_BASE}/api/v1/checkout/sessions/{checkout_id}",
        headers={"X-Api-Key": os.environ.get("RADIUMONE_SECRET_KEY", "")},
        timeout=30,
    )
    payload = resp.json()
    if not resp.ok:
        code = payload.get("code") or payload.get("type")
        raise RuntimeError(f"checkout session fetch failed: {code} ({resp.status_code})")
    # Confirm order_reference and amount match your order before fulfilling.
    return payload


if __name__ == "__main__":
    print(json.dumps(retrieve_checkout_session(), indent=2))

Branch on the status

processing: wait and re-check shortly — the shopper is actively completing payment, and cancelling mid-attempt isn’t supported.
completed: the payment already succeeded. Don’t retry the cancel — if you need to reverse it, refund the transaction through the Payments API instead.
failed / expired: the session is already terminal and never charged anything — no action needed.
cancelled: already done — treat the original conflicting call as resolved.

Retry the cancel only from pending

Once (or if) the session returns to pending, cancel is safe to call (API reference):

#!/usr/bin/env bash
# Merchant-initiated cancel (X-Api-Key, not CSRF/customer-driven). Idempotent
# while pending; 409 if already processing or terminal.
set -euo pipefail

CHECKOUT_BASE="${RADIUMONE_CHECKOUT_BASE:-https://checkout-sandbox.radiumone.io}"
: "${RADIUMONE_SECRET_KEY:?set RADIUMONE_SECRET_KEY to your r1sk_* secret key}"
: "${RADIUMONE_CHECKOUT_ID:?set RADIUMONE_CHECKOUT_ID to the session to cancel}"

curl -sS -X POST "$CHECKOUT_BASE/api/v1/checkout/sessions/$RADIUMONE_CHECKOUT_ID/cancel" \
  -H "X-Api-Key: $RADIUMONE_SECRET_KEY"

#!/usr/bin/env node
// Merchant-initiated cancel (X-Api-Key, not CSRF/customer-driven). Idempotent
// while pending; 409 if already processing or terminal. Node 18+ ESM fetch.
// Env: RADIUMONE_SECRET_KEY, RADIUMONE_CHECKOUT_ID, RADIUMONE_CHECKOUT_BASE.
const CHECKOUT_BASE = process.env.RADIUMONE_CHECKOUT_BASE || "https://checkout-sandbox.radiumone.io";
const secretKey = process.env.RADIUMONE_SECRET_KEY;
const checkoutId = process.env.RADIUMONE_CHECKOUT_ID;

async function cancelCheckoutSession() {
  const res = await fetch(`${CHECKOUT_BASE}/api/v1/checkout/sessions/${checkoutId}/cancel`, {
    method: "POST",
    headers: { "X-Api-Key": secretKey },
  });
  const payload = await res.json();
  if (!res.ok) {
    // 409 session:invalid_state if already processing/terminal.
    throw new Error(`checkout session cancel failed: ${payload.code ?? payload.type} (${res.status})`);
  }
  return payload;
}

cancelCheckoutSession().then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Merchant-initiated cancel (X-Api-Key, not CSRF/customer-driven). Idempotent
while pending; 409 if already processing or terminal.
"""
import json
import os

import requests

CHECKOUT_BASE = os.environ.get("RADIUMONE_CHECKOUT_BASE", "https://checkout-sandbox.radiumone.io")


def cancel_checkout_session() -> dict:
    checkout_id = os.environ["RADIUMONE_CHECKOUT_ID"]
    resp = requests.post(
        f"{CHECKOUT_BASE}/api/v1/checkout/sessions/{checkout_id}/cancel",
        headers={"X-Api-Key": os.environ.get("RADIUMONE_SECRET_KEY", "")},
        timeout=30,
    )
    payload = resp.json()
    if not resp.ok:
        # 409 session:invalid_state if already processing/terminal.
        code = payload.get("code") or payload.get("type")
        raise RuntimeError(f"checkout session cancel failed: {code} ({resp.status_code})")
    return payload


if __name__ == "__main__":
    print(json.dumps(cancel_checkout_session(), indent=2))

Session lifecycle

Full cancellation and TTL behavior.

API errors

The full error reference, including session:invalid_state.

Handle failures

All ten failure scenarios, symptom → page.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Cancellation conflicts - Hosted checkout

When this happens

What you see

What to do

Session lifecycle

API errors

Handle failures

​When this happens

​What you see

​What to do

​Related

Session lifecycle

API errors

Handle failures

When this happens

What you see

What to do

Related