> ## 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 EFT 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 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

* A user abandons the payment flow in your application
* You need to prevent session reuse for security reasons
* You want to clean up active sessions before their natural timeout
* You are implementing session cleanup workflows

### Authentication Requirements

Authenticate with a valid `access_token` from the [/Authorize](/api/pay/endpoints/authorize/authorize) endpoint.

### 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 behaves as if the session has timed out and displays an appropriate error state.
* **Status change**: session status changes to `Cancelled` with status details `EFT0501`.

If the session is already in a terminal state (`Completed`, `Cancelled`, or `Expired`), the request is rejected with a `400`.

## Implementation Notes

* If you do not call this endpoint, sessions automatically expire based on the timeout window defined during onboarding.
* 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": "850750a4-3021-4061-ac03-a8d873aa4179",
  "referenceId": "USER12345",
  "status": "Cancelled",
  "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 `Cancelled` for a successful cancellation)
* **statusDetails**: Status code `EFT0501`, indicating the session was cancelled by API request

## Status Code Reference

| Status | StatusDetails | Description |
| - | - | - |
| `Cancelled` | `EFT0501` | ⚫ Session cancelled by API request |

## Error Responses

### Session Already Terminal

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

### Authentication Required

Returned with `401` when the Bearer token is missing or invalid.

```json theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Valid access token required"
}
```

### Session Not Found

Returned with `404` when no session matches the provided `sessionId` for your client.

```json theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Session not found for client {{clientId}}"
}
```

## Webhook Notification

When a session is cancelled, a `SessionSetupStatusChanged` webhook event is sent to your configured subscription:

```json theme={null}
{
  "when": "2026-06-08T14:36:48.6078123Z",
  "payload": {
    "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
    "amount": 100.00,
    "referenceId": "USER12345",
    "status": "Cancelled",
    "statusDetails": "EFT0501"
  },
  "type": "SessionSetupStatusChanged"
}
```

## Best Practices

### Session Cleanup

* Call this endpoint when users navigate away from the payment flow
* Implement cleanup for abandoned sessions in your application

### Error Handling

* Handle cases where the session is already terminal
* Implement retry logic for transient network failures
* Log cancellation events for audit purposes

## Use Cases

### User Abandonment

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

### Timeout Management

```javascript theme={null}
// Cancel a session before its natural timeout
async function handleSessionTimeout(sessionId) {
  try {
    await cancelSession(sessionId);
  } catch (error) {
    console.error('Failed to cancel session:', error);
  }
}
```

## Related Endpoints

* [Initiate Session](/api/pay/endpoints/eft/v2/sessions-initiate): create an EFT payment session
* [Get Session Details](/api/pay/endpoints/eft/v2/sessions-details): retrieve comprehensive session information


## OpenAPI

````yaml openapi-pay-eft.yaml POST /api/v2/sessions/{sessionId}/cancel
openapi: 3.0.1
info:
  title: Flinks EFT API V2
  description: Flinks Electronic Funds Transfer (EFT) API v2.
  version: v2
servers: []
security: []
paths:
  /api/v2/sessions/{sessionId}/cancel:
    post:
      tags:
        - Sessions
      operationId: CancelSession
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: x-client-id
          in: header
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelSessionSetupResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    CancelSessionSetupResponse:
      type: object
      properties:
        sessionId:
          type: string
          format: uuid
        referenceId:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/SessionStatus'
        statusDetails:
          type: string
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    SessionStatus:
      enum:
        - Initiated
        - Failed
        - Cancelled
        - Expired
        - Completed
      type: string

````