Initiate Session

POST /api/v2/sessions

cURL

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": "[e-mail]"
  },
  "payee": {
    "account": {
      "institutionCode": "999",
      "transitNumber": "30265",
      "accountNumber": "9876541"
    }
  }
}'

201

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "referenceId": "<string>"
}

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

cURL

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": "[e-mail]"
  },
  "payee": {
    "account": {
      "institutionCode": "999",
      "transitNumber": "30265",
      "accountNumber": "9876541"
    }
  }
}'

Response

{
  "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 — retrieve full session information
• /Authorize — obtain an access token

Headers

x-client-id · string

Body

application/jsontext/jsonapplication/*+json

type · enum<string>

Available options: EFT, e-Transfer

direction · enum<string>

Available options: DEBIT, CREDIT

payor · object

Show child attributes

referenceId · string | null

currency · enum<string>

Available options: CAD

amount · number<decimal> | null

options · object

Show child attributes

payee · object

Show child attributes

Response

201

text/plain

Created

sessionId · string<uuid>

referenceId · string | null