> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flinks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api/pay/endpoints/authorize/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

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

## Response

```json theme={null}
{
  "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

```json theme={null}
{
  "error": "not_found",
  "error_description": "Session not found for client {{clientId}}"
}
```

### Authentication Required

```json theme={null}
{
  "error": "unauthorized",
  "error_description": "Valid access token required"
}
```

### Session Already Terminal

```json theme={null}
{
  "error": "invalid_request",
  "error_description": "Session {{sessionId}} cannot be Cancelled"
}
```

## Webhook Notification

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

```json theme={null}
{
  "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

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

### Timeout Management

```javascript theme={null}
// 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

```javascript theme={null}
// 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](/api/pay/endpoints/geft/sessions-initiate) - Initialize GEFT payment session
* [Get Session Status](/api/pay/endpoints/geft/sessions-status) - Monitor payment progress
* [Get Session Details](/api/pay/endpoints/geft/sessions-details) - Retrieve comprehensive session information


## OpenAPI

````yaml POST /api/v2/sessions/{sessionId}/cancel
openapi: 3.0.3
info:
  title: Flinks GEFT API
  description: >
    Flinks Guaranteed Electronic Funds Transfer (GEFT) API provides secure,
    guaranteed payment processing capabilities.


    ## Authentication

    All endpoints require authentication using Bearer tokens obtained from the
    /authorize endpoint.


    ## Overview

    GEFT is a payment service that lets you move funds from your customers' bank
    accounts via Electronic Funds Transfer,

    while Flinks assumes the EFT risk on your behalf. Once a payment is
    guaranteed, Flinks ensures that you (the Merchant)

    will not be required to reimburse or return any funds you receive from
    Flinks or from an end user.


    For more information, visit: https://docs.flinks.com
  version: 2.0.0
  contact:
    name: Flinks Support
    url: https://www.flinks.com/contact/sales
  termsOfService: https://www.flinks.com
servers:
  - url: https://www.{baseurl}.com
    description: Flinks Pay Production
    variables:
      baseurl:
        default: '{baseurl}'
        description: The base URI for the environment (e.g. flinks)
security:
  - BearerAuth: []
tags:
  - name: GEFT Sessions
    description: Create, monitor, and manage GEFT payment sessions
paths:
  /api/v2/sessions/{sessionId}/cancel:
    post:
      tags:
        - GEFT Sessions
      summary: Cancel GEFT Session
      description: >-
        Immediately terminate an active GEFT session so the user can no longer
        access or resume the flow.
      operationId: cancelGEFTSession
      parameters:
        - name: sessionId
          in: path
          required: true
          description: Unique session identifier to cancel.
          schema:
            type: string
            format: uuid
          example: 86095db9-7cb4-4121-a6ca-9d64368c6463
        - name: Authorization
          in: header
          required: true
          description: Bearer token received from /authorize endpoint.
          schema:
            type: string
            pattern: ^Bearer .+
      responses:
        '200':
          description: Session canceled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    format: uuid
                    description: Unique session identifier that was canceled.
                    example: 86095db9-7cb4-4121-a6ca-9d64368c6463
                  referenceId:
                    type: string
                    description: Reference ID associated with the session.
                    example: Happy2
                  status:
                    type: string
                    enum:
                      - Canceled
                    description: Status confirming cancellation.
                    example: Canceled
                  statusDetails:
                    type: string
                    enum:
                      - EFT0501
                    description: Status code indicating session canceled by API request.
                    example: EFT0501
              example:
                sessionId: 86095db9-7cb4-4121-a6ca-9d64368c6463
                referenceId: Happy2
                status: Canceled
                statusDetails: EFT0501
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type identifier
          example: invalid_request
        error_description:
          type: string
          description: Human-readable error description
          example: 'Missing required field: firstName'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from /api/v1/authorize endpoint

````