> ## 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 EFT session and obtain a `sessionId` for launching the user payment flow.
For regular EFT, set `type` to `EFT` and `options.guarantee.enable` to `false`.

Funds settle to your client's configured bank account — `payee` is not supported for EFT.
Requires the `RegularEft` feature to be enabled on your client (otherwise `403`).


Create a new EFT 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.

## Initiate an EFT Session

This endpoint creates a session on the **Regular EFT path** and returns a `sessionId` that your application uses to launch the hosted Flinks Pay flow — either by redirecting the user to the app URL or loading it in an iframe.

Set `type` to `EFT` and `options.guarantee.enable` to `false`. Funds settle to your client's configured bank account, so **`payee` is not supported** for EFT.

### Authentication Requirements

* You must authenticate and obtain a valid `access_token` from the [/Authorize](/api/pay/endpoints/authorize/authorize) endpoint.
* Create the session while the token is still valid (599 seconds). If it expires, re-authenticate and call this endpoint again.
* Your client must have the **RegularEft** feature enabled. If it is not, the request returns `403 Forbidden`.

### User Identity Matching

`firstName` and `lastName` are used for identity matching against the payor's 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**:

* It should uniquely identify the end user or transaction in your system.
* It appears in responses and reconciliation files for easy matching.
* For EFT it flows through as the cross-reference number, so it must be **1–36 alphanumeric characters or hyphens**.

### Amount Handling

* **When `amount` is provided** — the value is pre-set and the user cannot modify it in the flow. It must fall within your client's configured minimum/maximum EFT amount.
* **When `amount` is omitted** — the user enters the amount during the hosted flow.

### Payor Address

`payor.address` is **optional** for regular EFT. If you include it, address line 1, city, province, postal code, and country are required. (An address is only mandatory for Guaranteed EFT.)

### Launching the Payment Flow

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

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

## Request Example

<CodeGroup>
  ```bash cURL (minimum) 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",
    "payor": {
      "firstName": "Sara",
      "lastName": "Ahmad",
      "email": "sara.ahmad@example.com"
    },
    "options": {
      "guarantee": { "enable": false }
    }
  }'
  ```

  ```bash cURL (with optional fields) 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": 100.00,
    "options": {
      "guarantee": { "enable": false },
      "notificationPreferences": { "language": "EN" },
      "showConsentScreen": false
    },
    "payor": {
      "firstName": "Sara",
      "lastName": "Ahmad",
      "email": "sara.ahmad@example.com",
      "address": {
        "addressLine1": "123 Street",
        "city": "Toronto",
        "postalCode": "M5H2N2",
        "province": "ON",
        "country": "CA"
      }
    }
  }'
  ```
</CodeGroup>

## 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  | Required; used for notifications |
| `referenceId`           | 1–36 characters | Alphanumeric and hyphens only    |
| `postalCode`            | 6 characters    | No spaces (e.g., M5H2N2)         |
| `province`              | 2 characters    | Provincial code (e.g., ON, QC)   |
| `country`               | 2 characters    | Only `CA` supported              |

### Supported Province Codes

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

## Related Endpoints

* [Get Session Details](/api/pay/endpoints/eft/v2/sessions-details) — retrieve comprehensive session information
* [Cancel Session](/api/pay/endpoints/eft/v2/sessions-cancel) — terminate an active session


## OpenAPI

````yaml /openapi-pay-eft-v2.yaml POST /api/v2/sessions
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:
    post:
      tags:
        - Sessions
      summary: Initiate EFT Session
      description: >
        Create a new EFT session and obtain a `sessionId` for launching the user
        payment flow.

        For regular EFT, set `type` to `EFT` and `options.guarantee.enable` to
        `false`.


        Funds settle to your client's configured bank account — `payee` is not
        supported for EFT.

        Requires the `RegularEft` feature to be enabled on your client
        (otherwise `403`).
      operationId: initiateEftSession
      parameters:
        - name: Authorization
          in: header
          required: true
          description: Bearer token received from the /authorize endpoint.
          schema:
            type: string
            pattern: ^Bearer .+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateSessionRequest'
            example:
              referenceId: USER12345
              type: EFT
              direction: DEBIT
              currency: CAD
              amount: 100
              options:
                guarantee:
                  enable: false
                notificationPreferences:
                  language: EN
                showConsentScreen: false
              payor:
                firstName: Sara
                lastName: Ahmad
                email: sara.ahmad@example.com
                address:
                  addressLine1: 123 Street
                  city: Toronto
                  postalCode: M5H2N2
                  province: 'ON'
                  country: CA
      responses:
        '201':
          description: Session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateSessionSetupResponse'
              example:
                sessionId: 850750a4-3021-4061-ac03-a8d873aa4179
                referenceId: USER12345
        '400':
          description: >-
            Bad Request — validation error (e.g. direction not DEBIT, missing
            payor fields, payee present, amount out of range)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                title: Bad Request
                status: 400
                detail: Payee is not supported for EFT
        '401':
          description: Unauthorized — invalid or missing Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden — client does not have the RegularEft feature enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    InitiateSessionRequest:
      type: object
      required:
        - type
        - direction
        - payor
        - options
      properties:
        type:
          type: string
          enum:
            - EFT
          description: The payment rail. Must be `EFT` for this API.
          example: EFT
        direction:
          type: string
          enum:
            - DEBIT
          description: Payment direction. Only `DEBIT` is supported for EFT.
          example: DEBIT
        currency:
          type: string
          enum:
            - CAD
          default: CAD
          description: >-
            Currency code. Only `CAD` is supported (defaults to `CAD` if
            omitted).
          example: CAD
        amount:
          type: number
          format: double
          minimum: 0.01
          nullable: true
          description: >
            Payment amount, up to 2 decimal places. Optional — if omitted, the
            user enters the

            amount in the hosted flow. When provided, it must fall within the
            client's configured

            minimum/maximum EFT amount.
          example: 100
        referenceId:
          type: string
          maxLength: 36
          pattern: ^[a-zA-Z0-9\-]{1,36}$
          nullable: true
          description: >
            Your internal reference identifier (strongly recommended). 1–36
            alphanumeric characters

            or hyphens. Flows through as the EFT cross-reference number and
            appears in

            reconciliation files.
          example: USER12345
        options:
          $ref: '#/components/schemas/SessionSetupOptionModel'
        payor:
          $ref: '#/components/schemas/PartyInfoRequest'
    InitiateSessionSetupResponse:
      type: object
      properties:
        sessionId:
          type: string
          format: uuid
          description: >-
            Unique session identifier. Use it to launch the hosted flow and
            monitor the session.
          example: 850750a4-3021-4061-ac03-a8d873aa4179
        referenceId:
          type: string
          nullable: true
          description: The reference ID you supplied (if any).
          example: USER12345
    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
    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'
    PartyInfoRequest:
      type: object
      required:
        - firstName
        - lastName
        - email
      description: >
        The end user being debited. `firstName`, `lastName`, and `email` are
        required for regular

        EFT. `address` is optional for regular EFT (it is required only when a
        guarantee is enabled).
      properties:
        firstName:
          type: string
          description: >-
            Payor's first name. Used for identity matching against the bank
            account.
          example: Sara
        lastName:
          type: string
          description: >-
            Payor's last name. Used for identity matching against the bank
            account.
          example: Ahmad
        email:
          type: string
          format: email
          description: Payor's email address. Used for notifications.
          example: sara.ahmad@example.com
        middleName:
          type: string
          nullable: true
          description: Payor's middle name (optional).
        occupation:
          type: string
          nullable: true
          description: Payor's occupation (optional).
        birthDate:
          type: string
          nullable: true
          description: Payor's birth date in `yy-MM-dd` format (optional).
          example: 90-05-21
        address:
          allOf:
            - $ref: '#/components/schemas/BaseAddressModel'
          nullable: true
          description: >-
            Payor address (optional for regular EFT). If provided, address line
            1, city, province, postal code, and country are required.
    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
    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
    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.

````