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 Status - Monitor payment progress
Get Session Details - Retrieve comprehensive session information

Authorizations

Authorization

string

header

required

Bearer token obtained from /api/v1/authorize endpoint

Headers

Authorization

string

required

Bearer token received from /authorize endpoint.

Pattern: ^Bearer .+

Path Parameters

sessionId

string<uuid>

required

Unique session identifier to cancel.

Response

Session canceled successfully

sessionId

string<uuid>

Unique session identifier that was canceled.

Example:

"86095db9-7cb4-4121-a6ca-9d64368c6463"

referenceId

string

Reference ID associated with the session.

Example:

"Happy2"

status

enum<string>

Status confirming cancellation.

Available options:

Canceled

Example:

"Canceled"

statusDetails

enum<string>

Status code indicating session canceled by API request.

Available options:

EFT0501

Example:

"EFT0501"