Skip to main content
POST
/
api
/
v2
/
sessions
/
{sessionId}
/
cancel
Cancel GEFT Session
curl --request POST \
  --url https://www.{baseurl}.com/api/v2/sessions/{sessionId}/cancel \
  --header 'Authorization: Bearer <token>'
{
  "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

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

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"