Skip to main content
POST
/
api
/
v2
/
sessions
/
initiate
Create GEFT Session
curl --request POST \
  --url https://www.{baseurl}.com/api/v2/sessions/initiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "EFT",
  "direction": "DEBIT",
  "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"
    }
  }
}
'
{
  "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",
    "phone": "5551234567",
    "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
phone15 charactersNumbers only, no special characters
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 /api/v1/authorize endpoint

Headers

​
Authorization
string
required

Bearer token received from /authorize endpoint.

Pattern: ^Bearer .+

Body

application/json
​
type
enum<string>
required

The payment rail for the transaction.

Available options:
EFT
​
direction
enum<string>
required

Payment direction relative to the target account.

Available options:
DEBIT
​
options
object
required
​
payor
object
required
​
referenceId
string

Your internal reference ID for transaction tracking (strongly recommended).

Maximum string length: 100
Example:

"USER12345"

​
currency
enum<string>
default:CAD

Currency code for the payment.

Available options:
CAD
​
amount
number

Payment amount in dollars and cents. If omitted, user enters amount.

Required range: 0.01 <= x <= 99999.99Must be a multiple of 0.01
Example:

500

​
payee
object

Destination account information. If omitted, funds settle to configured default account.

Response

Session created successfully

​
sessionId
string<uuid>

Unique session identifier for launching payment flow.

Example:

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

​
referenceId
string

The reference ID provided in the request.

Example:

"USER12345"