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

Retrieve comprehensive session information including verified payor account details.

To successfully call this endpoint, you must have a valid access token from the [/Authorize](/api/pay/endpoints/authorize/authorize) endpoint.

## Get Session Details

Use this endpoint to retrieve full, verified payor account information along with all session-level details required for payment validation.

### Availability of Account Details

**Important**: Payor account details become available only after the session has passed the "Initiated" stage. Before that point, the payor account section will be returned empty.

This endpoint provides:

* **Complete session information**: All details from session creation
* **Verified account details**: Bank account information after user authentication
* **Payment validation data**: Information needed for transaction processing
* **Identity verification results**: User identity matching status

## Request Example

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

## Response Structure

The response includes comprehensive session information and, once available, detailed payor account verification data:

```json theme={null}
{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "status": "Completed",
  "step": {
    "current": "Complete",
    "aggregationRequestId": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
    "padId": "d4c3b2a1-f6e5-0987-dcba-fe7654321098"
  },
  "referenceId": "USER12345",
  "amount": 500.00,
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "options": {
    "guarantee": {
      "enable": true
    },
    "showConsentScreen": true,
    "limits": {
      "minimumAmount": 10,
      "maximumAmount": 1000
    }
  },
  "payor": {
    "email": "john.smith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "account": {
      "institutionCode": "014",
      "transitNumber": "58964",
      "accountNumber": "1234567",
      "accountLabel": "Account (****4567)"
    },
    "address": {
      "addressLine1": "123 Main Street",
      "city": "Toronto",
      "province": "ON",
      "country": "CA",
      "postalCode": "M5V3A8"
    }
  },
  "payee": {
    "account": {
      "institutionCode": "999",
      "transitNumber": "30265",
      "accountNumber": "9876541",
      "accountLabel": "Settlement Account"
    }
  },
  "guaranteeDetails": {
    "guaranteeOffered": true,
    "guaranteeAccepted": true,
    "highestDebitAmountToGuarantee": 500.00,
    "overallRiskLevel": "Low",
    "transactionRiskLevel": "Low",
    "userRiskLevel": "Low",
    "otherRiskLevel": "Unknown",
    "guaranteedEftType": "Full"
  },
  "userDetails": {
    "matchingPerformed": true,
    "nameMatch": 95
  }
}
```

## Response Fields

### Session Information

* **sessionId**: Unique session identifier
* **status**: Current session status
* **step**: Current step of the session flow — an object with `current`, `aggregationRequestId`, and `padId`. Possible `current` values:
  * `Start` — session opened; user has entered the flow
  * `Consent` — Flinks consent screen (when `showConsentScreen` is enabled)
  * `BankSelection` — user is choosing their financial institution
  * `BankConnection` — user is logging into / connecting their bank
  * `AccountSelection` — user is selecting which account to use
  * `AmountSelection` — user is entering the amount (skipped when `amount` is preset)
  * `GuaranteeOffer` — guarantee offer presented to the user
  * `Review` — user reviews the payment details
  * `Pad` — user reviews and signs the PAD agreement
  * `Complete` — flow finished
* **referenceId**: Your internal reference ID
* **amount**: Payment amount (null if not yet set)
* **type**: Payment type (always "EFT" for GEFT)
* **direction**: Payment direction (always "DEBIT" for GEFT)
* **currency**: Payment currency (always "CAD")

### Options

* **guarantee.enable**: Whether a guarantee was requested
* **notificationPreferences.language**: Language preference ("EN" or "FR")
* **showConsentScreen**: Whether Flinks consent screen is displayed
* **limits**: Minimum and maximum allowed payment amounts
* **amountModification**: Whether the user can modify the amount
* **redirectPreferences**: Redirect mode and URLs for session completion

### Payor Information

* **Personal details**: Name (firstName, lastName, middleName), email as provided during session creation
* **Verified account**: Bank account information obtained after user authentication (institutionCode, transitNumber, accountNumber, accountLabel, availableBalance)
* **Address**: Street address, city, province, country, postal code

### Payee Information

* **Account details**: Destination account information (institutionCode, transitNumber, accountNumber, accountLabel)

### Guarantee Details

* **guaranteeOffered**: Whether a guarantee was offered
* **guaranteeAccepted**: Whether the guarantee was accepted (null if not yet decided)
* **highestDebitAmountToGuarantee**: Maximum debit amount eligible for guarantee
* **Risk levels**: overallRiskLevel, transactionRiskLevel, userRiskLevel, otherRiskLevel (Unknown, Low, Medium, High)
* **guaranteedEftType**: Type of guarantee coverage (Full, Partial, Minimal)

### User Details

* **matchingPerformed**: Whether identity matching was performed
* **nameMatch**: Name matching score (0 to 100)

## Data Availability Timeline

### Before User Authentication (Status: Initiated)

```json theme={null}
{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "status": "Initiated",
  "referenceId": "USER12345",
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "payor": {
    "email": "john.smith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "account": null
  }
}
```

### After User Authentication (Status: Completed/Failed)

```json theme={null}
{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "status": "Completed",
  "payor": {
    "email": "john.smith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "account": {
      "institutionCode": "003",
      "transitNumber": "12345",
      "accountNumber": "****1234",
      "accountLabel": "Checking (****1234)"
    }
  }
}
```

## Use Cases

### Payment Validation

* Verify user identity matches bank account holder
* Confirm account details for reconciliation
* Validate guarantee status before processing

### Audit and Compliance

* Complete transaction trail for regulatory requirements
* Identity verification documentation
* Account verification records

### Customer Support

* Comprehensive session information for issue resolution
* Account details for payment troubleshooting
* Complete payment history and status

### Reconciliation

* Match payments to internal records using referenceId
* Account details for settlement verification
* Complete payment lifecycle information

## Error Responses

### Session Not Found

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

### Authentication Required

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

### Insufficient Permissions

```json theme={null}
{
  "error": "forbidden",
  "error_description": "Access denied to session details"
}
```

## Security Considerations

### Data Protection

* **Account numbers**: Masked for security (showing only last 4 digits)
* **Personal information**: Handle according to privacy regulations
* **Access controls**: Ensure proper authentication and authorization

### Compliance

* **Data retention**: Follow regulatory requirements for payment data
* **Audit trails**: Maintain complete records for compliance
* **Privacy**: Protect customer personal and financial information

## Best Practices

### When to Call This Endpoint

* **After status changes**: When polling shows status updates
* **For reconciliation**: During end-of-day processing
* **For support**: When investigating payment issues
* **For compliance**: When audit trails are required

### Data Handling

* **Cache appropriately**: Avoid excessive API calls
* **Secure storage**: Protect sensitive account information
* **Access logging**: Log all access to session details

## Status Values

The `status` field reflects the session's progress. Retrieve this endpoint until the session reaches a terminal state (`Completed`, `Failed`, `Canceled`, or `Expired`).

| Status      | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `Initiated` | 🟡 Session created; the user has not yet completed the flow |
| `Completed` | 🟢 Session completed                                        |
| `Failed`    | 🔴 Session failed                                           |
| `Canceled`  | ⚫ Session canceled by API request                           |
| `Expired`   | ⚫ Session timed out - user inactive or did not complete     |

## Related Endpoints

* [Create Session](/api/pay/endpoints/geft/sessions-initiate) - Initialize GEFT payment session
* [Cancel Session](/api/pay/endpoints/geft/sessions-cancel) - Terminate active session


## OpenAPI

````yaml GET /api/v2/sessions/{sessionId}/details
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}/details:
    get:
      tags:
        - Sessions
      summary: Get EFT Session Details
      description: >
        Retrieve comprehensive session information including verified payor
        account details (once

        available). Payor account details are populated only after the session
        passes the

        `Initiated` stage. `payee` is always `null` — funds settle to your
        configured account.
      operationId: getEftSessionDetails
      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 details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSetupResponse'
              example:
                sessionId: 850750a4-3021-4061-ac03-a8d873aa4179
                status: Completed
                step:
                  current: Complete
                  aggregationRequestId: c1a2b3d4-e5f6-7890-abcd-ef1234567890
                  padId: d4c3b2a1-f6e5-0987-dcba-fe7654321098
                referenceId: USER12345
                amount: 100
                type: EFT
                direction: DEBIT
                currency: CAD
                options:
                  guarantee:
                    enable: false
                  showConsentScreen: false
                  limits:
                    minimumAmount: 50
                    maximumAmount: 10000
                  amountModification: true
                  redirectPreferences:
                    mode: JsEvents
                payor:
                  email: sara.ahmad@example.com
                  firstName: Sara
                  lastName: Ahmad
                  account:
                    institutionCode: '003'
                    transitNumber: '12345'
                    accountNumber: '****1234'
                    accountLabel: Checking (****1234)
                  address:
                    addressLine1: 123 Street
                    city: Toronto
                    province: 'ON'
                    country: CA
                    postalCode: M5H2N2
                userDetails:
                  matchingPerformed: true
                  nameMatch: 95
                createdAt: '2026-06-04T14:30:00Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    SessionSetupResponse:
      type: object
      properties:
        sessionId:
          type: string
          format: uuid
          example: 850750a4-3021-4061-ac03-a8d873aa4179
        status:
          $ref: '#/components/schemas/SessionStatus'
        step:
          $ref: '#/components/schemas/CurrentStep'
        referenceId:
          type: string
          nullable: true
          example: USER12345
        amount:
          type: number
          format: double
          nullable: true
          example: 100
        type:
          type: string
          enum:
            - EFT
          example: EFT
        direction:
          type: string
          enum:
            - DEBIT
          example: DEBIT
        currency:
          type: string
          enum:
            - CAD
          example: CAD
        options:
          $ref: '#/components/schemas/SessionSetupOptionModel'
        payor:
          $ref: '#/components/schemas/PartyModel'
        payee:
          allOf:
            - $ref: '#/components/schemas/PartyModel'
          nullable: true
          description: Always `null` for EFT — funds settle to your configured account.
        userDetails:
          $ref: '#/components/schemas/UserDetails'
        schedule:
          $ref: '#/components/schemas/SessionScheduleModel'
        createdAt:
          type: string
          format: date-time
          example: '2026-06-04T14:30:00Z'
    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.
    CurrentStep:
      type: object
      properties:
        current:
          $ref: '#/components/schemas/SessionStep'
        aggregationRequestId:
          type: string
          format: uuid
          nullable: true
        padId:
          type: string
          format: uuid
          nullable: true
    SessionSetupOptionModel:
      type: object
      required:
        - guarantee
      properties:
        guarantee:
          $ref: '#/components/schemas/GuaranteeOptions'
        notificationPreferences:
          $ref: '#/components/schemas/NotificationPreferencesOptions'
        showConsentScreen:
          type: boolean
          nullable: true
          description: Whether to display the Flinks consent screen.
          example: false
        limits:
          $ref: '#/components/schemas/SessionLimitsModel'
        amountModification:
          type: boolean
          description: Whether the user can modify the amount in the hosted flow.
        redirectPreferences:
          $ref: '#/components/schemas/RedirectPreferencesResponse'
    PartyModel:
      type: object
      properties:
        email:
          type: string
          nullable: true
          example: sara.ahmad@example.com
        firstName:
          type: string
          nullable: true
          example: Sara
        lastName:
          type: string
          nullable: true
          example: Ahmad
        middleName:
          type: string
          nullable: true
        account:
          allOf:
            - $ref: '#/components/schemas/AccountInfoModel'
          nullable: true
          description: >-
            Verified bank account, populated after user authentication. `null`
            while the session is still `Initiated`.
        address:
          $ref: '#/components/schemas/BaseAddressModel'
    UserDetails:
      type: object
      properties:
        matchingPerformed:
          type: boolean
          description: Whether identity matching was performed.
          example: true
        nameMatch:
          type: number
          format: double
          description: Name matching score (0 to 100).
          example: 95
    SessionScheduleModel:
      type: object
      properties:
        transactions:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SessionTransactionModel'
    SessionStep:
      type: string
      enum:
        - Start
        - Consent
        - BankSelection
        - BankConnection
        - AccountSelection
        - AmountSelection
        - Review
        - Pad
        - Complete
      description: Current step in the session flow.
    GuaranteeOptions:
      type: object
      required:
        - enable
      properties:
        enable:
          type: boolean
          description: >-
            Must be `false` for regular EFT. Set to `true` only for Guaranteed
            EFT (GEFT).
          example: false
    NotificationPreferencesOptions:
      type: object
      properties:
        language:
          type: string
          enum:
            - EN
            - FR
          default: EN
          description: Language preference for notifications.
          example: EN
    SessionLimitsModel:
      type: object
      properties:
        minimumAmount:
          type: number
          format: double
          nullable: true
          description: Minimum allowed payment amount.
          example: 50
        maximumAmount:
          type: number
          format: double
          nullable: true
          description: Maximum allowed payment amount.
          example: 10000
    RedirectPreferencesResponse:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/RedirectPreferencesMode'
        urlSuccess:
          type: string
          format: uri
          nullable: true
        urlExit:
          type: string
          format: uri
          nullable: true
    AccountInfoModel:
      type: object
      properties:
        institutionCode:
          type: string
          nullable: true
          example: '003'
        transitNumber:
          type: string
          nullable: true
          example: '12345'
        accountNumber:
          type: string
          nullable: true
          description: Masked, showing only the last 4 digits.
          example: '****1234'
        accountLabel:
          type: string
          nullable: true
          example: Checking (****1234)
        availableBalance:
          type: number
          format: double
          nullable: true
    BaseAddressModel:
      type: object
      properties:
        addressLine1:
          type: string
          example: 123 Street
        addressLine2:
          type: string
          nullable: true
        unit:
          type: string
          nullable: true
        city:
          type: string
          example: Toronto
        province:
          type: string
          description: 2-character provincial code (e.g. ON, QC).
          example: 'ON'
        country:
          type: string
          description: 2-character ISO country code. Only `CA` is supported.
          example: CA
        postalCode:
          type: string
          description: Postal code, no spaces (e.g. M5H2N2).
          example: M5H2N2
    SessionTransactionModel:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          nullable: true
    RedirectPreferencesMode:
      type: string
      enum:
        - JsEvents
        - RedirectUri
      description: How the hosted flow returns control when the session completes.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from the /api/v1/authorize endpoint.

````