> ## 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 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 EFT API (V2)
  description: >
    Flinks EFT (Electronic Funds Transfer) API — **V2, session-based**.


    V2 replaces V1's endpoint-by-endpoint integration with a single
    session-based flow built on the

    shared `/api/v2/sessions` model. You create one session (`type = EFT`,

    `options.guarantee.enable = false`), launch the hosted Flinks Pay flow, and
    monitor the session

    to completion. This is the **Regular EFT path**; guarantee features are part
    of the GEFT product.


    ## Authentication

    All endpoints authenticate using a Bearer token obtained from the
    `/api/v1/authorize` endpoint

    (OAuth 2.0 Client Credentials). The session `status` endpoint requires only
    the `sessionId`.


    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: Sessions
    description: Create, monitor, and manage EFT payment sessions
paths:
  /api/v2/sessions/{sessionId}/cancel:
    post:
      tags:
        - Sessions
      summary: Cancel EFT Session
      description: >
        Immediately terminate an active EFT session so the user can no longer
        access or resume the

        flow. If the session is already in a terminal state (Completed,
        Cancelled, Expired), the

        request is rejected.
      operationId: cancelEftSession
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The session identifier returned when the session was created.
          schema:
            type: string
            format: uuid
          example: 850750a4-3021-4061-ac03-a8d873aa4179
        - name: Authorization
          in: header
          required: true
          description: Bearer token received from the /authorize endpoint.
          schema:
            type: string
            pattern: ^Bearer .+
      responses:
        '200':
          description: Session cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelSessionSetupResponse'
              example:
                sessionId: 850750a4-3021-4061-ac03-a8d873aa4179
                referenceId: USER12345
                status: Cancelled
                statusDetails: EFT0501
        '400':
          description: Bad Request — session cannot be cancelled (already terminal)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                title: Bad Request
                status: 400
                detail: >-
                  Session 850750a4-3021-4061-ac03-a8d873aa4179 cannot be
                  Cancelled
        '401':
          description: Unauthorized — invalid or missing Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    CancelSessionSetupResponse:
      type: object
      properties:
        sessionId:
          type: string
          format: uuid
          example: 850750a4-3021-4061-ac03-a8d873aa4179
        referenceId:
          type: string
          nullable: true
          example: USER12345
        status:
          $ref: '#/components/schemas/SessionStatus'
        statusDetails:
          type: string
          nullable: true
          description: >-
            Status detail code. `EFT0501` indicates the session was cancelled by
            API request.
          example: EFT0501
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
          example: https://tools.ietf.org/html/rfc7231#section-6.5.1
        title:
          type: string
          nullable: true
          example: Bad Request
        status:
          type: integer
          format: int32
          nullable: true
          example: 400
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
    SessionStatus:
      type: string
      enum:
        - Initiated
        - Failed
        - Cancelled
        - Expired
        - Completed
      description: Current session status.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from the /api/v1/authorize endpoint.

````