Session Details - Flinks Documentation

Get EFT Session Details

curl --request GET \
  --url https://www.{baseurl}.com/api/v2/sessions/{sessionId}/details \
  --header 'Authorization: Bearer <token>'

{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "status": "Completed",
  "step": {
    "current": "Complete",
    "aggregationRequestId": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
    "padId": "d4c3b2a1-f6e5-0987-dcba-fe7654321098"
  },
  "referenceId": "USER12345",
  "amount": 100,
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "options": {
    "guarantee": {
      "enable": false
    },
    "showConsentScreen": false,
    "limits": {
      "minimumAmount": 50,
      "maximumAmount": 10000
    },
    "amountModification": true,
    "redirectPreferences": {
      "mode": "JsEvents"
    }
  },
  "payor": {
    "email": "sara.ahmad@example.com",
    "firstName": "Sara",
    "lastName": "Ahmad",
    "account": {
      "institutionCode": "003",
      "transitNumber": "12345",
      "accountNumber": "****1234",
      "accountLabel": "Checking (****1234)"
    },
    "address": {
      "addressLine1": "123 Street",
      "city": "Toronto",
      "province": "ON",
      "country": "CA",
      "postalCode": "M5H2N2"
    }
  },
  "userDetails": {
    "matchingPerformed": true,
    "nameMatch": 95
  },
  "createdAt": "2026-06-04T14:30:00Z"
}

GET

api

sessions

{sessionId}

details

Get EFT Session Details

curl --request GET \
  --url https://www.{baseurl}.com/api/v2/sessions/{sessionId}/details \
  --header 'Authorization: Bearer <token>'

{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "status": "Completed",
  "step": {
    "current": "Complete",
    "aggregationRequestId": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
    "padId": "d4c3b2a1-f6e5-0987-dcba-fe7654321098"
  },
  "referenceId": "USER12345",
  "amount": 100,
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "options": {
    "guarantee": {
      "enable": false
    },
    "showConsentScreen": false,
    "limits": {
      "minimumAmount": 50,
      "maximumAmount": 10000
    },
    "amountModification": true,
    "redirectPreferences": {
      "mode": "JsEvents"
    }
  },
  "payor": {
    "email": "sara.ahmad@example.com",
    "firstName": "Sara",
    "lastName": "Ahmad",
    "account": {
      "institutionCode": "003",
      "transitNumber": "12345",
      "accountNumber": "****1234",
      "accountLabel": "Checking (****1234)"
    },
    "address": {
      "addressLine1": "123 Street",
      "city": "Toronto",
      "province": "ON",
      "country": "CA",
      "postalCode": "M5H2N2"
    }
  },
  "userDetails": {
    "matchingPerformed": true,
    "nameMatch": 95
  },
  "createdAt": "2026-06-04T14:30:00Z"
}

Retrieve comprehensive session information, including verified payor account details. To successfully call this endpoint, you must have a valid access token from the /Authorize endpoint.

Get Session Details

Use this endpoint to retrieve full session information along with the verified payor account details captured during the hosted flow.

Availability of Account Details

Important: Payor account details become available only after the session has passed the Initiated stage. Before that point, payor.account is returned as null. payee is always null — funds settle to your client’s configured account.

Request Example

curl --location '{{BaseUri}}/api/v2/sessions/{{sessionId}}/details' \
--header 'Authorization: Bearer {{access_token}}'

Response Structure

{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "status": "Completed",
  "step": {
    "current": "Complete",
    "aggregationRequestId": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
    "padId": "d4c3b2a1-f6e5-0987-dcba-fe7654321098"
  },
  "referenceId": "USER12345",
  "amount": 100.00,
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "options": {
    "guarantee": { "enable": false },
    "showConsentScreen": false,
    "limits": { "minimumAmount": 50.00, "maximumAmount": 10000.00 },
    "amountModification": true,
    "redirectPreferences": { "mode": "JsEvents" }
  },
  "payor": {
    "email": "sara.ahmad@example.com",
    "firstName": "Sara",
    "lastName": "Ahmad",
    "account": {
      "institutionCode": "003",
      "transitNumber": "12345",
      "accountNumber": "****1234",
      "accountLabel": "Checking (****1234)"
    },
    "address": {
      "addressLine1": "123 Street",
      "city": "Toronto",
      "province": "ON",
      "country": "CA",
      "postalCode": "M5H2N2"
    }
  },
  "userDetails": {
    "matchingPerformed": true,
    "nameMatch": 95
  },
  "createdAt": "2026-06-04T14:30:00Z"
}

Response Fields

Session Information

sessionId: Unique session identifier
status: Current session status
step: Current step of the session flow — an object with current, aggregationRequestId, and padId. Possible current values:
- Start — session opened; user has entered the flow
- Consent — Flinks consent screen (when showConsentScreen is enabled)
- BankSelection — user is choosing their financial institution
- BankConnection — user is logging into / connecting their bank
- AccountSelection — user is selecting which account to use
- AmountSelection — user is entering the amount (skipped when amount is preset)
- Review — user reviews the payment details
- Pad — user reviews and signs the PAD agreement
- Complete — flow finished
referenceId: Your internal reference ID
amount: Payment amount (null if not yet set)
type: Payment type (always EFT)
direction: Payment direction (always DEBIT)
currency: Payment currency (always CAD)

Options

guarantee.enable: Whether a guarantee was requested (always false for regular EFT)
notificationPreferences.language: Language preference (EN or FR)
showConsentScreen: Whether the Flinks consent screen is displayed
limits: Minimum and maximum allowed payment amounts
amountModification: Whether the user can modify the amount
redirectPreferences: Redirect mode and URLs for session completion

Payor Information

Personal details: firstName, lastName, middleName, email as provided during session creation
Verified account: Bank account information obtained after user authentication (institutionCode, transitNumber, accountNumber, accountLabel). Account numbers are masked, showing only the last 4 digits.
Address: Street address, city, province, country, postal code

Payee Information

payee: Always null for EFT — funds settle to your configured account.

User Details

matchingPerformed: Whether identity matching was performed
nameMatch: Name matching score (0 to 100)

Data Availability Timeline

Before user authentication (Status: Initiated)

{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "status": "Initiated",
  "referenceId": "USER12345",
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "payor": {
    "email": "sara.ahmad@example.com",
    "firstName": "Sara",
    "lastName": "Ahmad",
    "account": null
  },
  "payee": null
}

After user authentication (Status: Completed/Failed)

{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "status": "Completed",
  "payor": {
    "email": "sara.ahmad@example.com",
    "firstName": "Sara",
    "lastName": "Ahmad",
    "account": {
      "institutionCode": "003",
      "transitNumber": "12345",
      "accountNumber": "****1234",
      "accountLabel": "Checking (****1234)"
    }
  }
}

Status Values

The status field reflects the session’s progress. Retrieve this endpoint until the session reaches a terminal state (Completed, Failed, Cancelled, or Expired).

Status	Description
`Initiated`	🟡 Session created; the user has not yet completed the flow
`Completed`	🟢 Session completed — PAD signed and EFT transaction scheduled
`Failed`	🔴 Session failed (for example, a login, identity, or balance issue)
`Cancelled`	⚫ Session cancelled by API request
`Expired`	⚫ Session timed out — user inactive or did not complete

Guarantee-related outcomes do not apply to regular EFT — they are specific to GEFT.

Use Cases

Payment Validation

Verify the user’s identity matches the bank account holder
Confirm account details for reconciliation
Confirm the session reached a terminal state before processing

Audit and Compliance

Complete transaction trail for regulatory requirements
Identity verification documentation
Account verification records

Customer Support

Comprehensive session information for issue resolution
Account details for payment troubleshooting
Complete payment status

Reconciliation

Match payments to internal records using referenceId
Account details for settlement verification
Complete payment lifecycle information

Error Responses

Session Not Found

Returned with 404 when no session matches the provided sessionId.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Session not found"
}

Authentication Required

Returned with 401 when the Bearer token is missing or invalid.

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Valid access token required"
}

Security Considerations

Data Protection

Account numbers: masked for security (showing only the last 4 digits)
Personal information: handle according to privacy regulations
Access controls: ensure proper authentication and authorization

Compliance

Data retention: follow regulatory requirements for payment data
Audit trails: maintain complete records for compliance
Privacy: protect customer personal and financial information

Best Practices

When to Call This Endpoint

After a status change: when you detect a session update (for example, via webhook)
For reconciliation: during end-of-day processing
For support: when investigating payment issues
For compliance: when audit trails are required

Data Handling

Cache appropriately: avoid excessive API calls
Secure storage: protect sensitive account information
Access logging: log all access to session details

Initiate Session — create an EFT payment session
Cancel Session — terminate an active session

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

Path Parameters

sessionId

string<uuid>

required

The session identifier returned when the session was created.

Response

Session details retrieved successfully

sessionId

string<uuid>

Example:

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

status

enum<string>

Current session status.

Available options:

Initiated,

Failed,

Cancelled,

Expired,

Completed

step

object

Show child attributes

referenceId

string | null

Example:

"USER12345"

amount

number<double> | null

Example:

100

type

enum<string>

Available options:

EFT

Example:

"EFT"

direction

enum<string>

Available options:

DEBIT

Example:

"DEBIT"

currency

enum<string>

Available options:

CAD

Example:

"CAD"

options

object

Show child attributes

payor

object

Show child attributes

payee

object

Always null for EFT — funds settle to your configured account.

Show child attributes

userDetails

object

Show child attributes

schedule

object

Show child attributes

createdAt

string<date-time>

Example:

"2026-06-04T14:30:00Z"

Initiate Session

Cancel Active Session

⌘I

​Get Session Details

​Availability of Account Details

​Request Example

​Response Structure

​Response Fields

​Session Information

​Options

​Payor Information

​Payee Information

​User Details

​Data Availability Timeline

​Before user authentication (Status: Initiated)

​After user authentication (Status: Completed/Failed)

​Status Values

​Use Cases

​Payment Validation

​Audit and Compliance

​Customer Support

​Reconciliation

​Error Responses

​Session Not Found

​Authentication Required

​Security Considerations

​Data Protection

​Compliance

​Best Practices

​When to Call This Endpoint

​Data Handling

​Related Endpoints

Authorizations

Headers

Path Parameters

Response

Get Session Details

Availability of Account Details

Request Example

Response Structure

Response Fields

Session Information

Options

Payor Information

Payee Information

User Details

Data Availability Timeline

Before user authentication (Status: Initiated)

After user authentication (Status: Completed/Failed)

Status Values

Use Cases

Payment Validation

Audit and Compliance

Customer Support

Reconciliation

Error Responses

Session Not Found

Authentication Required

Security Considerations

Data Protection

Compliance

Best Practices

When to Call This Endpoint

Data Handling

Related Endpoints