Cancel Active Session

POST /api/v2/sessions/{sessionId}/cancel

Cancel GEFT Session

cURL

curl --request POST \
  --url https://www.{baseurl}.com/api/v2/sessions/{sessionId}/cancel \
  --header 'Authorization: Bearer <token>'

200

{
  "sessionId": "86095db9-7cb4-4121-a6ca-9d64368c6463",
  "referenceId": "Happy2",
  "status": "Canceled",
  "statusDetails": "EFT0501"
}

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.

Cancel Active Session

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`);
}

Related Endpoints

• 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

200

application/json

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"