Skip to main content
POST
/
api
/
v2
/
sessions
Initiate EFT Session
curl --request POST \
  --url https://www.{baseurl}.com/api/v2/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "EFT",
  "direction": "DEBIT",
  "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"
    }
  }
}
'
{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "referenceId": "USER12345"
}
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 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

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

{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "referenceId": "USER12345"
}

​
Field Specifications

​
Character Limits

FieldLimitNotes
firstName, lastName100 charactersRequired for identity matching
email100 charactersUsed for notifications
referenceId100 charactersStrongly recommended for tracking
postalCode6 charactersNo spaces (e.g., M5V0T7)
province2 charactersProvincial code (e.g., ON, QC)
accountNumberBetween 7 and 12 charactersNumbers only
transitNumber5 charactersNumbers only
institutionCode3 charactersNumbers 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

Authorizations

​
Authorization
string
header
required

Bearer token obtained from the /api/v1/authorize endpoint.

Headers

​
Authorization
string
required

Bearer token received from the /authorize endpoint.

Pattern: ^Bearer .+

Body

application/json
​
type
enum<string>
required

The payment rail. Must be EFT for this API.

Available options:
EFT
Example:

"EFT"

​
direction
enum<string>
required

Payment direction. Only DEBIT is supported for EFT.

Available options:
DEBIT
Example:

"DEBIT"

​
options
object
required
​
payor
object
required

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

​
currency
enum<string>
default:CAD

Currency code. Only CAD is supported (defaults to CAD if omitted).

Available options:
CAD
Example:

"CAD"

​
amount
number<double> | null

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.

Required range: x >= 0.01
Example:

100

​
referenceId
string | null

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.

Maximum string length: 36
Pattern: ^[a-zA-Z0-9\-]{1,36}$
Example:

"USER12345"

Response

Session created successfully

​
sessionId
string<uuid>

Unique session identifier. Use it to launch the hosted flow and monitor the session.

Example:

"850750a4-3021-4061-ac03-a8d873aa4179"

​
referenceId
string | null

The reference ID you supplied (if any).

Example:

"USER12345"