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

# Initiate Session

Create a new GEFT session and obtain a sessionId for launching the user payment flow.

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

## Create a GEFT Session

This endpoint creates a GEFT session and returns a `sessionId` that your application uses to launch the GEFT user flow in the hosted iFrame.

### Authentication Requirements

* You must authenticate and obtain a valid `access_token`
* Create the session while the token is still valid (599 seconds)
* If the token expires, re-authenticate and call this endpoint again

### Destination Account Logic

GEFT supports routing payments to different destinations:

* **With payee object**: Funds are settled to the specified account
* **Without payee object**: Flinks automatically uses your client's configured settlement account
* **No payee + no settlement account configured**: Request will be rejected with an error

Flinks records the resolved destination account in the session so each transaction remains fully traceable.

### User Identity Matching

Fields such as `firstName` and `lastName` are used for identity matching against the external bank account. They must accurately reflect the person who owns the external account expected to make the payment.

**Critical**: If the provided name differs significantly from the name on the linked bank account, the session will return an error (EFT0403) and the transaction will not be processed.

### Reference ID Best Practices

While `referenceId` is not mandatory, it is **strongly recommended**:

* In production, should uniquely identify the end user or transaction in your system
* Appears in responses and reconciliation files for easy matching
* Makes support requests much easier to resolve
* Used in sandbox to trigger specific test scenarios

### Amount Handling

**When amount is provided:**

* Value is pre-set for the user
* End user cannot modify the amount in the payment flow
* "Enter an amount" step is displayed, but grayed out
* Amount cannot be updated during any later phase of the session lifecycle
* No Next Best Offer (NBO) will be created with a preset amount

**When amount is omitted:**

* User enters amount during the payment flow
* Min/max limits (if configured) are enforced
* Next Best Offer may be presented if the requested amount cannot be guaranteed

### Launching the Payment Flow

Once you have a sessionId, launch the GEFT user flow by directing users to:

```text theme={null}
{{BaseUri}}/app/?sessionId={{sessionId}}
```

## Field Specifications

### Character Limits

| Field | Limit | Notes |
| - | - | - |
| `firstName`, `lastName` | 140 characters combined | Required for identity matching |
| `email` | 256 characters | Used for notifications |
| `referenceId` | 36 characters | Strongly recommended for tracking |
| `addressLine1` | 70 characters | Street address |
| `city` | 35 characters | Full city name |
| `postalCode` | 10 characters | e.g., M5V0T7, M5V 0T7, 90210, 90210-1234 |
| `province` | 2 characters | Provincial code (e.g., ON, QC) |
| `country` | 2 characters | Only "CA" supported |
| `accountNumber` | Between 7 and 12 digits | Numbers only |
| `transitNumber` | 5 digits | Numbers only |
| `institutionCode` | 3 digits | Numbers only |

### Supported Province Codes

AB, BC, MB, NB, NL, NT, NS, NU, ON, PE, QC, SK, YT

## Account Label Display

Control how the "To Account" line is displayed in the UI using the `accountLabel` field:

1. **`accountLabel` provided**: Same text shown in "To Account" section
2. **`accountLabel` omitted, payee account present**: Flinks builds label using existing logic
3. **`accountLabel` omitted, no payee account**: "To Account" section is hidden

## Related Endpoints

* [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 openapi-pay-geft.yaml POST /api/v2/sessions
openapi: 3.0.1
info:
  title: Flinks GEFT API
  description: Flinks Guaranteed Electronic Funds Transfer (GEFT) API.
  version: v2
servers: []
security: []
paths:
  /api/v2/sessions:
    post:
      tags:
        - Sessions
      operationId: InitiateSession
      parameters:
        - name: x-client-id
          in: header
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateSessionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateSessionSetupResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    InitiateSessionRequest:
      type: object
      properties:
        referenceId:
          type: string
          nullable: true
        type:
          $ref: '#/components/schemas/PaymentType'
        direction:
          $ref: '#/components/schemas/PaymentDirection'
        currency:
          $ref: '#/components/schemas/PaymentCurrency'
        amount:
          type: number
          format: decimal
          nullable: true
        options:
          $ref: '#/components/schemas/SessionSetupOptionRequest'
        payor:
          $ref: '#/components/schemas/PayorInfoRequest'
        payee:
          $ref: '#/components/schemas/PayeeInfoRequest'
      additionalProperties: false
    InitiateSessionSetupResponse:
      type: object
      properties:
        sessionId:
          type: string
          format: uuid
        referenceId:
          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: {}
    PaymentType:
      enum:
        - EFT
        - e-Transfer
      type: string
      default: EFT
    PaymentDirection:
      enum:
        - DEBIT
        - CREDIT
      type: string
      default: DEBIT
    PaymentCurrency:
      enum:
        - CAD
      type: string
    SessionSetupOptionRequest:
      type: object
      properties:
        guarantee:
          $ref: '#/components/schemas/GuaranteeOptions'
        notificationPreferences:
          $ref: '#/components/schemas/NotificationPreferencesOptions'
        showConsentScreen:
          type: boolean
          nullable: true
      additionalProperties: false
    PayorInfoRequest:
      type: object
      properties:
        email:
          type: string
          nullable: true
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        middleName:
          type: string
          nullable: true
        occupation:
          type: string
          nullable: true
        birthDate:
          type: string
          nullable: true
        account:
          $ref: '#/components/schemas/PayorAccountInfoRequest'
        address:
          $ref: '#/components/schemas/BaseAddressModel'
      additionalProperties: false
    PayeeInfoRequest:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/PayeeAccountInfoRequest'
      additionalProperties: false
    GuaranteeOptions:
      type: object
      properties:
        enable:
          type: boolean
          default: true
      additionalProperties: false
    NotificationPreferencesOptions:
      type: object
      properties:
        language:
          $ref: '#/components/schemas/Language'
      additionalProperties: false
    PayorAccountInfoRequest:
      type: object
      properties:
        accountId:
          type: string
          format: uuid
          nullable: true
        institutionCode:
          type: string
          nullable: true
        transitNumber:
          type: string
          nullable: true
        accountNumber:
          type: string
          nullable: true
        accountLabel:
          type: string
          nullable: true
      additionalProperties: false
    BaseAddressModel:
      type: object
      properties:
        addressLine1:
          type: string
          nullable: true
        addressLine2:
          type: string
          nullable: true
        unit:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        province:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        postalCode:
          type: string
          nullable: true
      additionalProperties: false
    PayeeAccountInfoRequest:
      type: object
      properties:
        institutionCode:
          type: string
          nullable: true
        transitNumber:
          type: string
          nullable: true
        accountNumber:
          type: string
          nullable: true
        accountLabel:
          type: string
          nullable: true
      additionalProperties: false
    Language:
      enum:
        - EN
        - FR
      type: string

````