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

```
{{BaseUri}}/app/?sessionId={{sessionId}}
```

## Request Example

```bash theme={null}
curl --location '{{BaseUri}}/api/v2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "referenceId": "USER12345",
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "amount": 500.00,
  "options": {
    "guarantee": {
      "enable": true
    },
    "notificationPreferences": {
      "language": "EN"
    }
  },
  "payor": {
    "firstName": "Jean-Claude",
    "lastName": "Topinambour",
    "email": "mrflinks@flinks.com",
    "address": {
      "addressLine1": "123 street",
      "city": "Montreal",
      "postalCode": "h2eh2e",
      "province": "QC",
      "country": "CA"
    }
  },
  "payee": {
    "account": {
      "accountNumber": "9876541",
      "transitNumber": "30265",
      "institutionCode": "999"
    }
  }
}'
```

## Response

```json theme={null}
{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "referenceId": "USER12345"
}
```

## Field Specifications

### Character Limits

| Field                   | Limit                       | Notes                             |
| ----------------------- | --------------------------- | --------------------------------- |
| `firstName`, `lastName` | 100 characters              | Required for identity matching    |
| `email`                 | 100 characters              | Used for notifications            |
| `referenceId`           | 100 characters              | Strongly recommended for tracking |
| `postalCode`            | 6 characters                | No spaces (e.g., M5V0T7)          |
| `province`              | 2 characters                | Provincial code (e.g., ON, QC)    |
| `accountNumber`         | Between 7 and 12 characters | Numbers only                      |
| `transitNumber`         | 5 characters                | Numbers only                      |
| `institutionCode`       | 3 characters                | 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 Status](/api/pay/endpoints/geft/sessions-status) - Monitor payment progress
* [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 POST /api/v2/sessions
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:
    post:
      tags:
        - GEFT Sessions
      summary: Create GEFT Session
      description: >-
        Create a new GEFT session and obtain a sessionId for launching the user
        payment flow.
      operationId: createGEFTSession
      parameters:
        - name: Authorization
          in: header
          required: true
          description: Bearer token received from /authorize endpoint.
          schema:
            type: string
            pattern: ^Bearer .+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - direction
                - options
                - payor
              properties:
                referenceId:
                  type: string
                  maxLength: 100
                  description: >-
                    Your internal reference ID for transaction tracking
                    (strongly recommended).
                  example: USER12345
                type:
                  type: string
                  enum:
                    - EFT
                  description: The payment rail for the transaction.
                direction:
                  type: string
                  enum:
                    - DEBIT
                  description: Payment direction relative to the target account.
                currency:
                  type: string
                  enum:
                    - CAD
                  default: CAD
                  description: Currency code for the payment.
                amount:
                  type: number
                  multipleOf: 0.01
                  maximum: 99999.99
                  minimum: 0.01
                  description: >-
                    Payment amount in dollars and cents. If omitted, user enters
                    amount.
                  example: 500
                options:
                  type: object
                  required:
                    - guarantee
                  properties:
                    guarantee:
                      type: object
                      required:
                        - enable
                      properties:
                        enable:
                          type: boolean
                          enum:
                            - true
                          description: >-
                            Must be true to request a guarantee and generate
                            GEFT user experience.
                    notificationPreferences:
                      type: object
                      properties:
                        language:
                          type: string
                          enum:
                            - EN
                            - FR
                          default: EN
                          description: Language preference for notifications.
                    showConsentScreen:
                      type: boolean
                      default: true
                      description: Whether to display Flinks consent screen.
                payor:
                  type: object
                  required:
                    - firstName
                    - lastName
                  properties:
                    firstName:
                      type: string
                      maxLength: 100
                      description: >-
                        User's first name for identity matching against bank
                        account.
                      example: Jean-Claude
                    lastName:
                      type: string
                      maxLength: 100
                      description: >-
                        User's last name for identity matching against bank
                        account.
                      example: Topinambour
                    email:
                      type: string
                      maxLength: 100
                      format: email
                      description: User's email address for notifications.
                      example: mrflinks@flinks.com
                    middleName:
                      type: string
                      maxLength: 100
                      description: User's middle name.
                    occupation:
                      type: string
                      maxLength: 100
                      description: User's occupation.
                      example: teacher
                    dateOfBirth:
                      type: string
                      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
                      description: User's date of birth in YYYY-MM-DD format.
                      example: '1985-03-15'
                    address:
                      type: object
                      properties:
                        addressLine1:
                          type: string
                          maxLength: 100
                          description: Street address.
                          example: 123 street
                        city:
                          type: string
                          maxLength: 100
                          description: City name.
                          example: Montreal
                        postalCode:
                          type: string
                          maxLength: 6
                          pattern: ^[A-Za-z0-9]{6}$
                          description: Postal code without spaces (e.g., M5V0T7).
                          example: h2eh2e
                        province:
                          type: string
                          enum:
                            - AB
                            - BC
                            - MB
                            - NB
                            - NL
                            - NT
                            - NS
                            - NU
                            - 'ON'
                            - PE
                            - QC
                            - SK
                            - YT
                          description: Provincial code.
                          example: QC
                        country:
                          type: string
                          enum:
                            - CA
                          description: Country code (only CA supported).
                          example: CA
                payee:
                  type: object
                  description: >-
                    Destination account information. If omitted, funds settle to
                    configured default account.
                  properties:
                    account:
                      type: object
                      required:
                        - accountNumber
                        - transitNumber
                        - institutionCode
                      properties:
                        accountNumber:
                          type: string
                          maxLength: 15
                          pattern: ^[0-9]+$
                          description: Destination account number (numbers only).
                          example: '9876541'
                        transitNumber:
                          type: string
                          maxLength: 5
                          pattern: ^[0-9]+$
                          description: Transit number of destination account.
                          example: '30265'
                        institutionCode:
                          type: string
                          maxLength: 3
                          pattern: ^[0-9]+$
                          description: Institution code of destination account.
                          example: '999'
                        accountLabel:
                          type: string
                          maxLength: 100
                          description: Custom label for "To Account" display in UI.
                          example: Settlement Account
            example:
              referenceId: USER12345
              type: EFT
              direction: DEBIT
              currency: CAD
              amount: 500
              options:
                guarantee:
                  enable: true
                notificationPreferences:
                  language: EN
                showConsentScreen: false
              payor:
                firstName: Jean-Claude
                lastName: Topinambour
                email: mrflinks@flinks.com
                phone: '5551234567'
                occupation: teacher
                dateOfBirth: '1985-03-15'
                address:
                  addressLine1: 123 street
                  city: Montreal
                  postalCode: h2eh2e
                  province: QC
                  country: CA
              payee:
                account:
                  accountNumber: '9876541'
                  transitNumber: '30265'
                  institutionCode: '999'
                  accountLabel: Settlement Account
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    format: uuid
                    description: Unique session identifier for launching payment flow.
                    example: 850750a4-3021-4061-ac03-a8d873aa4179
                  referenceId:
                    type: string
                    description: The reference ID provided in the request.
                    example: USER12345
              example:
                sessionId: 850750a4-3021-4061-ac03-a8d873aa4179
                referenceId: USER12345
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
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

````