Cancel Active Session

Immediately terminate an active GEFT 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 Guaranteed 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

User abandons the payment flow in your application
Need to prevent session reuse for security reasons
Want to clean up active sessions before their natural timeout
Implementing session cleanup workflows

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 will behave as if the session has timed out and display an appropriate error state
Status change: Session status changes to “Canceled” with status details “EFT0501”

Implementation Notes

Recommended but not required:

If you do not call this endpoint, sessions will automatically expire based on the timeout window defined during onboarding
If you want 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": "86095db9-7cb4-4121-a6ca-9d64368c6463",
  "referenceId": "Happy2",
  "status": "Canceled",
  "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 “Canceled” for successful cancellation)
statusDetails: Status code “EFT0501” indicating session was canceled by API request

Status Code Reference

Status	StatusDetails	Description
`Canceled`	`EFT0501`	⚫ Session canceled by API request

Error Responses

Session Not Found

{
  "error": "not_found",
  "error_description": "Session not found for client {{clientId}}"
}

Authentication Required

{
  "error": "unauthorized",
  "error_description": "Valid access token required"
}

Session Already Terminal

{
  "error": "invalid_request",
  "error_description": "Session {{sessionId}} cannot be Cancelled"
}

Webhook Notification

When a session is successfully canceled, a webhook event is triggered:

{
  "when": "2025-11-18T14:36:48.6078123Z",
  "payload": {
    "sessionId": "c14b050b-6268-4f5c-9c73-80713c80edb3",
    "amount": 65,
    "referenceId": "Happy1",
    "status": "Canceled",
    "statusDetails": "EFT0501"
  },
  "type": "SessionSetupStatusChanged"
}

Best Practices

Session Cleanup

Call this endpoint when users navigate away from payment flow
Implement cleanup for abandoned sessions in your application
Consider batch cleanup for old active sessions

Error Handling

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

User Experience

Provide clear messaging when canceling sessions
Allow users to restart payment flow after cancellation
Maintain session state in your application for recovery

Use Cases

User Abandonment

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

Timeout Management

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

Security Cleanup

// Batch cleanup of abandoned sessions
async function cleanupAbandonedSessions(sessionIds) {
  const results = await Promise.allSettled(
    sessionIds.map(id => cancelSession(id))
  );

  const successful = results.filter(r => r.status === 'fulfilled');
  console.log(`Cleaned up ${successful.length} sessions`);
}

Create Session - Initialize GEFT 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"