Cancel Active Session

Immediately terminate an active EFT session to prevent further user access or resumption. To successfully call this endpoint, you must have a valid access token from the /Authorize endpoint.

Use this endpoint to immediately close an active session so the user can no longer access or resume the EFT flow. This is useful when a user abandons the flow in your application and you want to ensure the session cannot be reused.

When to Use This Endpoint

A user abandons the payment flow in your application
You need to prevent session reuse for security reasons
You want to clean up active sessions before their natural timeout
You are implementing session cleanup workflows

Authentication Requirements

Authenticate with a valid access_token from the /Authorize endpoint.

Session Termination Behavior

When you call this endpoint with a valid sessionId:

Immediate termination: the session is terminated immediately.
Frontend handling: the hosted front-end behaves as if the session has timed out and displays an appropriate error state.
Status change: session status changes to Cancelled with status details EFT0501.

If the session is already in a terminal state (Completed, Cancelled, or Expired), the request is rejected with a 400.

Implementation Notes

If you do not call this endpoint, sessions automatically expire based on the timeout window defined during onboarding.
To end a session before that timeout, you must call this endpoint.

Request Example

curl --location '{{BaseUri}}/api/v2/sessions/{{sessionId}}/cancel' \
--header 'Authorization: Bearer {{access_token}}' \
--request POST

Response

{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "referenceId": "USER12345",
  "status": "Cancelled",
  "statusDetails": "EFT0501"
}

Response Fields

sessionId: Unique session identifier for the terminated session
referenceId: Your internal reference ID (if provided during session creation)
status: Session status (always Cancelled for a successful cancellation)
statusDetails: Status code EFT0501, indicating the session was cancelled by API request

Status Code Reference

Status	StatusDetails	Description
`Cancelled`	`EFT0501`	⚫ Session cancelled by API request

Error Responses

Session Already Terminal

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Session 850750a4-3021-4061-ac03-a8d873aa4179 cannot be Cancelled"
}

Authentication Required

Returned with 401 when the Bearer token is missing or invalid.

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Valid access token required"
}

Session Not Found

Returned with 404 when no session matches the provided sessionId for your client.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Session not found for client {{clientId}}"
}

Webhook Notification

When a session is cancelled, a SessionSetupStatusChanged webhook event is sent to your configured subscription:

{
  "when": "2026-06-08T14:36:48.6078123Z",
  "payload": {
    "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
    "amount": 100.00,
    "referenceId": "USER12345",
    "status": "Cancelled",
    "statusDetails": "EFT0501"
  },
  "type": "SessionSetupStatusChanged"
}

Best Practices

Session Cleanup

Call this endpoint when users navigate away from the payment flow
Implement cleanup for abandoned sessions in your application

Error Handling

Handle cases where the session is already terminal
Implement retry logic for transient network failures
Log cancellation events for audit purposes

Use Cases

User Abandonment

// User navigates away from the payment page
window.addEventListener('beforeunload', async function() {
  if (activeSessionId && !paymentCompleted) {
    await cancelSession(activeSessionId);
  }
});

Timeout Management

// Cancel a session before its natural timeout
async function handleSessionTimeout(sessionId) {
  try {
    await cancelSession(sessionId);
  } catch (error) {
    console.error('Failed to cancel session:', error);
  }
}

Initiate Session — create an EFT payment session
Get Session Details — retrieve comprehensive session information

Authorizations

Authorization

string

header

required

Bearer token obtained from the /api/v1/authorize endpoint.

Headers

Authorization

string

required

Bearer token received from the /authorize endpoint.

Pattern: ^Bearer .+

Path Parameters

sessionId

string<uuid>

required

The session identifier returned when the session was created.

Response

Session cancelled successfully

sessionId

string<uuid>

Example:

"850750a4-3021-4061-ac03-a8d873aa4179"

referenceId

string | null

Example:

"USER12345"

status

enum<string>

Current session status.

Available options:

Initiated,

Failed,

Cancelled,

Expired,

Completed

statusDetails

string | null

Status detail code. EFT0501 indicates the session was cancelled by API request.

Example:

"EFT0501"