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

# Session Status

> Retrieve the current status of a GEFT session at any point in the flow.

Retrieve the current status of a GEFT session at any point in the flow.

This endpoint does not require authentication — you only need the session ID.

## Get Session Status

Use this endpoint to retrieve the current status of a Guaranteed EFT session. The response includes the current session status, amount information, and detailed status codes.

Call this endpoint periodically (for example, every \~30 seconds) until the status reflects a terminal state.

### Status Information Returned

* **Current session status**: See the status codes table below
* **Reference ID**: If one was provided when the session was created
* **Amount requested**: For guarantee (null if not yet set or entered by user)

The status returned primarily describes the user flow and any front-end outcome or error (for example, success, user exited, login failure, PAD rejected, session timeout).

## Request Example

```bash theme={null}
curl --location '{{BaseUri}}/api/v2/sessions/{{sessionId}}/status'
```

## Response

```json theme={null}
{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "referenceId": "USER12345",
  "amount": 500,
  "status": "Completed",
  "statusDetails": "EFT0301"
}
```

## Status Codes

| Status      | StatusDetails | Description                                                 |
| ----------- | ------------- | ----------------------------------------------------------- |
| `Initiated` | `EFT0101`     | 🟡 Session created, awaiting user start                     |
| `Completed` | `EFT0301`     | 🟢 Transaction scheduled, session fully completed           |
| `Completed` | `EFT0302`     | 🟠 Bank account validated, awaiting PAD signature           |
| `Failed`    | `EFT0401`     | 🔴 Login failed - invalid financial institution credentials |
| `Failed`    | `EFT0402`     | 🔴 Eligibility failed - no guaranteed EFT offered           |
| `Failed`    | `EFT0403`     | 🔴 Identity failed - invalid user information verification  |
| `Failed`    | `EFT0404`     | 🔴 Eligibility failed - insufficient available balance      |
| `Canceled`  | `EFT0501`     | ⚫ Session canceled by API request                           |
| `Expired`   | `EFT0601`     | ⚫ Session timed out - user inactive or did not complete     |

### Status Details Explained

**EFT0101 - Session Created**: A SessionId has been created and Flinks is awaiting for the user to start the session.

**EFT0301 - Transaction Scheduled**: The user has successfully completed the session and a transaction schedule has been instructed. User is fully complete - transaction information can be checked for status of the schedule.

**EFT0302 - Bank Account Validated**: The user has successfully validated their account (if required) - however, Flinks is awaiting the user to sign the PAD.

**EFT0401 - Login Failed**: The user was not able to successfully login to their Financial Institution (received an invalid login).

**EFT0402 - Eligibility Failed**: The user was not offered a Guaranteed EFT because of their account information (for example NSF or overall risk).

**EFT0403 - Identity Failed**: Invalid user information from their Financial Institution did not match provided user information, hence the session has failed.

**EFT0404 - Eligibility Failed (Insufficient Balance)**: The user was not offered a Guaranteed EFT because the available balance in their account was insufficient.

**EFT0501 - Session Canceled**: A call to the [/Sessions/Cancel](/api/pay/endpoints/geft/sessions-cancel) endpoint was made with the associated SessionId.

**EFT0601 - Session Timed Out**: The sessionId timed-out before the user completed the session.

## Polling Implementation

### Recommended Polling Strategy

```javascript theme={null}
async function pollSessionStatus(sessionId) {
  const terminalStates = ['Completed', 'Failed', 'Canceled', 'Expired'];
  const maxAttempts = 20;
  const pollInterval = 30000; // 30 seconds

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const response = await fetch(
        `{{BaseUri}}/api/v2/sessions/${sessionId}/status`
      );

      const status = await response.json();
      console.log(`Status check ${attempt + 1}:`, status);

      if (terminalStates.includes(status.status)) {
        return status;
      }

      await new Promise(resolve => setTimeout(resolve, pollInterval));
    } catch (error) {
      console.error('Status polling error:', error);
    }
  }

  throw new Error('Polling timeout - session status unknown');
}
```

### Alternative: Event-Based Monitoring

Instead of polling, consider using [frontend events](/guides/pay/geft/event-handling) for real-time status updates:

```javascript theme={null}
window.addEventListener('message', function(e) {
  if (e.data.Step === 'SUCCESS') {
    // Payment completed successfully
  } else if (e.data.Step === 'GUARANTEE_FAILED') {
    // Guarantee declined, offer alternatives
  }
});
```

## Error Responses

### Session Not Found

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

## Best Practices

### Polling Frequency

* **Recommended interval**: Every 30 seconds
* **Avoid aggressive polling**: Don't poll more frequently than every 10 seconds
* **Set timeout limits**: Implement maximum polling attempts

### Terminal State Handling

* **Success states**: `Completed` with `EFT0301` or `EFT0302`
* **Failure states**: `Failed`, `Canceled`, `Expired`
* **Implement retry logic**: For certain failure scenarios where appropriate

### Error Handling

* **Network errors**: Implement retry logic with exponential backoff
* **Session timeouts**: Handle gracefully with user messaging

## 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
* [Cancel Session](/api/pay/endpoints/geft/sessions-cancel) - Terminate active session


## OpenAPI

````yaml GET /api/v2/sessions/{sessionId}/status
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}/status:
    get:
      tags:
        - GEFT Sessions
      summary: Get GEFT Session Status
      description: Retrieve the current status of a GEFT session at any point in the flow.
      operationId: getGEFTSessionStatus
      parameters:
        - name: sessionId
          in: path
          required: true
          description: Unique session identifier obtained from session creation.
          schema:
            type: string
            format: uuid
          example: aadd08f2-83ce-456d-84ed-c68cfed4ee7b
      responses:
        '200':
          description: Session status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    format: uuid
                    description: Unique session identifier.
                    example: aadd08f2-83ce-456d-84ed-c68cfed4ee7b
                  referenceId:
                    type: string
                    description: Reference ID provided during session creation.
                    example: USER12345
                  amount:
                    type: number
                    nullable: true
                    description: >-
                      Amount requested for guarantee (null if not set or entered
                      yet).
                    example: 500
                  status:
                    type: string
                    enum:
                      - Initiated
                      - Completed
                      - Failed
                      - Canceled
                      - Expired
                    description: Current session status.
                    example: Completed
                  statusDetails:
                    type: string
                    enum:
                      - EFT0101
                      - EFT0301
                      - EFT0302
                      - EFT0401
                      - EFT0402
                      - EFT0403
                      - EFT0404
                      - EFT0501
                      - EFT0601
                    description: Detailed status code providing additional information.
                    example: EFT0301
              example:
                sessionId: aadd08f2-83ce-456d-84ed-c68cfed4ee7b
                referenceId: USER12345
                amount: 500
                status: Completed
                statusDetails: EFT0301
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []
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

````