> ## 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 Interac e-Transfer 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 e-Transfer Session

This endpoint creates an e-Transfer (Request For Money) session and returns a `sessionId` that your application uses to launch the hosted user flow—either by redirecting the user to the app URL, loading it in an iframe, or letting Flinks deliver an Interac link by email.

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

### User Identity Matching

The `firstName`, `lastName`, and (optionally) `middleName` fields 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 fail and the transaction will not be processed.

### Reference ID Best Practices

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

* In production, it 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
* Amount cannot be updated during any later phase of the session lifecycle

### Notification Preferences

Use `options.notificationPreferences` to control how the end user is notified:

* `sendInteracLink` — when `true`, Flinks sends the Interac e-Transfer request link directly to `payor.email`. When `false` (or omitted), you are responsible for distributing the hosted app URL yourself.

### Payor and Payee

* **`payor`** — required. Identifies the end user requested to pay. At minimum, include `firstName`, `lastName`, and `email`.
* **`payee`** — optional for e-Transfer. When omitted, funds are sent to your configured default settlement account.

### Payee Account (Optional)

The `payee.account` object lets you specify which destination account should receive the funds:

* **When `payee.account` is provided** — funds are routed to the account you specify (`institutionCode`, `transitNumber`, `accountNumber`). Use this when you need per-session routing (for example, settling to different merchant accounts).
* **When `payee.account` is omitted** — Flinks falls back to the default client bank account configured during onboarding. If no default account is configured on your client, the request is rejected.

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

### Launching the Payment Flow

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

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

If `sendInteracLink` is `true`, Flinks will email the link directly to the payor.

<RequestExample>
  ```bash cURL theme={null}
  curl --location '{{BaseUri}}/api/v2/sessions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{access_token}}' \
  --data-raw '{
    "referenceId": "USER12345",
    "type": "e-Transfer",
    "direction": "DEBIT",
    "currency": "CAD",
    "amount": 250.00,
    "options": {
      "notificationPreferences": {
        "sendInteracLink": true
      }
    },
    "payor": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com"
    },
    "payee": {
      "account": {
        "institutionCode": "999",
        "transitNumber": "30265",
        "accountNumber": "9876541"
      }
    }
  }'
  ```

  ```json Body theme={null}
  {
    "referenceId": "USER12345",
    "type": "e-Transfer",
    "direction": "DEBIT",
    "currency": "CAD",
    "amount": 250.00,
    "options": {
      "notificationPreferences": {
        "sendInteracLink": true
      }
    },
    "payor": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com"
    },
    "payee": {
      "account": {
        "institutionCode": "999",
        "transitNumber": "30265",
        "accountNumber": "9876541"
      }
    }
  }
  ```
</RequestExample>

## Response

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

## Field Specifications

### Character Limits

| Field                                 | Limit           | Notes                                    |
| ------------------------------------- | --------------- | ---------------------------------------- |
| `firstName`, `lastName`, `middleName` | 100 characters  | Required for identity matching           |
| `email`                               | 100 characters  | Used for notifications and link delivery |
| `referenceId`                         | 100 characters  | Strongly recommended for tracking        |
| `accountNumber`                       | 7–12 characters | Numbers only                             |
| `transitNumber`                       | 5 characters    | Numbers only                             |
| `institutionCode`                     | 3 characters    | Numbers only                             |

## Related Endpoints

* [Session Details](/api/pay/endpoints/e-transfer/sessions-details) — retrieve full session information
* [/Authorize](/api/pay/endpoints/authorize/authorize) — obtain an access token


## OpenAPI

````yaml /pay-interac.yaml POST /api/v2/sessions
openapi: 3.0.1
info:
  title: Flinks Interac API
  description: Flinks E-Transfer (RFM) 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'
          text/json:
            schema:
              $ref: '#/components/schemas/InitiateSessionRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/InitiateSessionRequest'
      responses:
        '201':
          description: Created
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/InitiateSessionSetupResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateSessionSetupResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/InitiateSessionSetupResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    InitiateSessionRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/PaymentType'
        direction:
          $ref: '#/components/schemas/PaymentDirection'
        payor:
          $ref: '#/components/schemas/PartyInfoRequest'
        referenceId:
          type: string
          nullable: true
        currency:
          $ref: '#/components/schemas/PaymentCurrency'
        amount:
          type: number
          format: decimal
          nullable: true
        options:
          $ref: '#/components/schemas/SessionSetupOptionModel'
        payee:
          $ref: '#/components/schemas/PartyInfoRequest'
      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
    PaymentDirection:
      enum:
        - DEBIT
        - CREDIT
      type: string
    PartyInfoRequest:
      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/AccountInfoRequest'
        address:
          $ref: '#/components/schemas/BaseAddressModel'
      additionalProperties: false
    PaymentCurrency:
      enum:
        - CAD
      type: string
    SessionSetupOptionModel:
      type: object
      properties:
        guarantee:
          $ref: '#/components/schemas/GuaranteeOptions'
        notificationPreferences:
          $ref: '#/components/schemas/NotificationPreferencesOptions'
        showConsentScreen:
          type: boolean
          nullable: true
        limits:
          $ref: '#/components/schemas/SessionLimitsModel'
        amountModification:
          type: boolean
        redirectPreferences:
          $ref: '#/components/schemas/RedirectPreferencesResponse'
      additionalProperties: false
    AccountInfoRequest:
      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
    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
    GuaranteeOptions:
      type: object
      properties:
        enable:
          type: boolean
      additionalProperties: false
    NotificationPreferencesOptions:
      type: object
      properties:
        language:
          $ref: '#/components/schemas/Language'
        sendInteracLink:
          type: boolean
          nullable: true
      additionalProperties: false
    SessionLimitsModel:
      type: object
      properties:
        minimumAmount:
          type: number
          format: decimal
          nullable: true
        maximumAmount:
          type: number
          format: decimal
          nullable: true
      additionalProperties: false
    RedirectPreferencesResponse:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/RedirectPreferencesMode'
        urlSuccess:
          type: string
          format: uri
          nullable: true
        urlExit:
          type: string
          format: uri
          nullable: true
      additionalProperties: false
    Language:
      enum:
        - EN
        - FR
      type: string
    RedirectPreferencesMode:
      enum:
        - JsEvents
        - RedirectUri
      type: string

````