Session Details - Flinks Documentation

Get GEFT Session Details

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

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "step": {
    "aggregationRequestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "padId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "referenceId": "<string>",
  "amount": 123,
  "type": "<string>",
  "direction": "<string>",
  "currency": "<string>",
  "options": {
    "guarantee": {
      "enable": true
    },
    "notificationPreferences": {},
    "showConsentScreen": true,
    "limits": {
      "minimumAmount": 123,
      "maximumAmount": 123
    },
    "amountModification": true,
    "redirectPreferences": {
      "urlSuccess": "<string>",
      "urlExit": "<string>"
    }
  },
  "payor": {
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "middleName": "<string>",
    "account": {
      "institutionCode": "<string>",
      "transitNumber": "<string>",
      "accountNumber": "<string>",
      "accountLabel": "<string>",
      "availableBalance": 123
    },
    "address": {
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "unit": "<string>",
      "city": "<string>",
      "province": "<string>",
      "country": "<string>",
      "postalCode": "<string>"
    }
  },
  "payee": {
    "account": {
      "institutionCode": "<string>",
      "transitNumber": "<string>",
      "accountNumber": "<string>",
      "accountLabel": "<string>"
    }
  },
  "guaranteeDetails": {
    "guaranteeOffered": true,
    "guaranteeAccepted": true,
    "highestDebitAmountToGuarantee": 123
  },
  "userDetails": {
    "matchingPerformed": true,
    "nameMatch": 123
  }
}

GET

api

sessions

{sessionId}

details

Get GEFT Session Details

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

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "step": {
    "aggregationRequestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "padId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "referenceId": "<string>",
  "amount": 123,
  "type": "<string>",
  "direction": "<string>",
  "currency": "<string>",
  "options": {
    "guarantee": {
      "enable": true
    },
    "notificationPreferences": {},
    "showConsentScreen": true,
    "limits": {
      "minimumAmount": 123,
      "maximumAmount": 123
    },
    "amountModification": true,
    "redirectPreferences": {
      "urlSuccess": "<string>",
      "urlExit": "<string>"
    }
  },
  "payor": {
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "middleName": "<string>",
    "account": {
      "institutionCode": "<string>",
      "transitNumber": "<string>",
      "accountNumber": "<string>",
      "accountLabel": "<string>",
      "availableBalance": 123
    },
    "address": {
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "unit": "<string>",
      "city": "<string>",
      "province": "<string>",
      "country": "<string>",
      "postalCode": "<string>"
    }
  },
  "payee": {
    "account": {
      "institutionCode": "<string>",
      "transitNumber": "<string>",
      "accountNumber": "<string>",
      "accountLabel": "<string>"
    }
  },
  "guaranteeDetails": {
    "guaranteeOffered": true,
    "guaranteeAccepted": true,
    "highestDebitAmountToGuarantee": 123
  },
  "userDetails": {
    "matchingPerformed": true,
    "nameMatch": 123
  }
}

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, verified payor account information along with all session-level details required for payment validation.

Availability of Account Details

Important: Payor account details become available only after the session has passed the “Initiated” stage. Before that point, the payor account section will be returned empty. This endpoint provides:

Complete session information: All details from session creation
Verified account details: Bank account information after user authentication
Payment validation data: Information needed for transaction processing
Identity verification results: User identity matching status

Request Example

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

Response Structure

The response includes comprehensive session information and, once available, detailed payor account verification data:

{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "status": "Completed",
  "step": {
    "current": "Complete",
    "aggregationRequestId": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
    "padId": "d4c3b2a1-f6e5-0987-dcba-fe7654321098"
  },
  "referenceId": "USER12345",
  "amount": 500.00,
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "options": {
    "guarantee": {
      "enable": true
    },
    "showConsentScreen": true,
    "limits": {
      "minimumAmount": 10,
      "maximumAmount": 1000
    }
  },
  "payor": {
    "email": "john.smith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "account": {
      "institutionCode": "014",
      "transitNumber": "58964",
      "accountNumber": "1234567",
      "accountLabel": "Account (****4567)"
    },
    "address": {
      "addressLine1": "123 Main Street",
      "city": "Toronto",
      "province": "ON",
      "country": "CA",
      "postalCode": "M5V3A8"
    }
  },
  "payee": {
    "account": {
      "institutionCode": "999",
      "transitNumber": "30265",
      "accountNumber": "9876541",
      "accountLabel": "Settlement Account"
    }
  },
  "guaranteeDetails": {
    "guaranteeOffered": true,
    "guaranteeAccepted": true,
    "highestDebitAmountToGuarantee": 500.00,
    "overallRiskLevel": "Low",
    "transactionRiskLevel": "Low",
    "userRiskLevel": "Low",
    "otherRiskLevel": "Unknown",
    "guaranteedEftType": "Full"
  },
  "userDetails": {
    "matchingPerformed": true,
    "nameMatch": 95
  }
}

Response Fields

Session Information

sessionId: Unique session identifier
status: Current session status
step: Current step of the session flow (current, aggregationRequestId, padId)
referenceId: Your internal reference ID
amount: Payment amount (null if not yet set)
type: Payment type (always “EFT” for GEFT)
direction: Payment direction (always “DEBIT” for GEFT)
currency: Payment currency (always “CAD”)

Options

guarantee.enable: Whether a guarantee was requested
notificationPreferences.language: Language preference (“EN” or “FR”)
showConsentScreen: Whether 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: Name (firstName, lastName, middleName), email as provided during session creation
Verified account: Bank account information obtained after user authentication (institutionCode, transitNumber, accountNumber, accountLabel, availableBalance)
Address: Street address, city, province, country, postal code

Payee Information

Account details: Destination account information (institutionCode, transitNumber, accountNumber, accountLabel)

Guarantee Details

guaranteeOffered: Whether a guarantee was offered
guaranteeAccepted: Whether the guarantee was accepted (null if not yet decided)
highestDebitAmountToGuarantee: Maximum debit amount eligible for guarantee
Risk levels: overallRiskLevel, transactionRiskLevel, userRiskLevel, otherRiskLevel (Unknown, Low, Medium, High)
guaranteedEftType: Type of guarantee coverage (Full, Partial, Minimal)

User Details

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

Data Availability Timeline

Before User Authentication (Status: Initiated)

{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "status": "Initiated",
  "referenceId": "USER12345",
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "payor": {
    "email": "john.smith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "account": null
  }
}

After User Authentication (Status: Completed/Failed)

{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "status": "Completed",
  "payor": {
    "email": "john.smith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "account": {
      "institutionCode": "003",
      "transitNumber": "12345",
      "accountNumber": "****1234",
      "accountLabel": "Checking (****1234)"
    }
  }
}

Use Cases

Payment Validation

Verify user identity matches bank account holder
Confirm account details for reconciliation
Validate guarantee status 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 history and status

Reconciliation

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

Error Responses

Session Not Found

{
  "error": "not_found",
  "error_description": "Session not found"
}

Authentication Required

{
  "error": "unauthorized",
  "error_description": "Valid access token required"
}

Insufficient Permissions

{
  "error": "forbidden",
  "error_description": "Access denied to session details"
}

Security Considerations

Data Protection

Account numbers: Masked for security (showing only 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 status changes: When polling shows status updates
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

Create Session - Initialize GEFT payment session
Get Session Status - Monitor payment progress
Cancel Session - Terminate active session

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

Path Parameters

sessionId

string<uuid>

required

Unique session identifier obtained from session creation.

Response

Session details retrieved successfully

sessionId

string<uuid>

Unique session identifier.

status

string

Current session status.

step

object

Show child attributes

referenceId

string

Reference ID provided during session creation.

amount

number

Payment amount.

type

string

Payment type (EFT).

direction

string

Payment direction (DEBIT).

currency

string

Payment currency (CAD).

options

object

Configuration parameters set during session initiation.

Show child attributes

payor

object

Payor information including verified account details (available after Initiated stage).

Show child attributes

payee

object

Payee account information.

Show child attributes

guaranteeDetails

object

Guarantee evaluation details for the session.

Show child attributes

userDetails

object

Identity verification results from user matching.

Show child attributes

Session Status

Confirm Guarantee

⌘I

​Get Session Details

​Availability of Account Details

​Request Example

​Response Structure

​Response Fields

​Session Information

​Options

​Payor Information

​Payee Information

​Guarantee Details

​User Details

​Data Availability Timeline

​Before User Authentication (Status: Initiated)

​After User Authentication (Status: Completed/Failed)

​Use Cases

​Payment Validation

​Audit and Compliance

​Customer Support

​Reconciliation

​Error Responses

​Session Not Found

​Authentication Required

​Insufficient Permissions

​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

Guarantee Details

User Details

Data Availability Timeline

Before User Authentication (Status: Initiated)

After User Authentication (Status: Completed/Failed)

Use Cases

Payment Validation

Audit and Compliance

Customer Support

Reconciliation

Error Responses

Session Not Found

Authentication Required

Insufficient Permissions

Security Considerations

Data Protection

Compliance

Best Practices

When to Call This Endpoint

Data Handling

Related Endpoints