GEFT API Overview

The GEFT (Guaranteed Electronic Funds Transfer) API provides enterprise-grade payment processing with guaranteed settlement for EFT transactions. This API reference covers all endpoints needed to integrate GEFT payments.

Base URLs

Production: {{BaseUri}} Sandbox: {{BaseUri}}

Authentication

All GEFT API requests use OAuth 2.0 Client Credentials flow:

Authenticate with Basic auth using Client ID and Secret
Receive Bearer token valid for 599 seconds (10 minutes)
Use Bearer token for all subsequent API calls
Refresh token before expiration

API Endpoints

Authentication

Method	Endpoint	Description
POST	`/api/v1/authorize`	Obtain access token

Session Management

Method	Endpoint	Description
POST	`/api/v2/sessions`	Create GEFT session
GET	`/api/v2/sessions/{sessionId}/details`	Get session details
POST	`/api/v2/sessions/{sessionId}/guarantees/confirm`	Confirm Guarantee Decision
POST	`/api/v2/sessions/{sessionId}/cancel`	Cancel session

Quick Start

1. Authenticate

curl --location '{{BaseUri}}/api/v1/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {{Username:Password}}' \
--data-urlencode 'grant_type=client_credentials'

2. Create Session

curl --location '{{BaseUri}}/api/v2/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw '{
  "referenceId": "USER12345",
  "type": "EFT",
  "direction": "DEBIT",
  "options": {
    "guarantee": {
      "enable": true
    }
  },
  "payor": {
    "firstName": "John",
    "lastName": "Smith",
    "address": {
      "addressLine1": "123 street",
      "city": "Toronto",
      "postalCode": "h2eh2e",
      "province": "ON",
      "country": "CA"
    }
  }
}'

3. Launch User Flow

<iframe
  src="{{BaseUri}}/app/?sessionId={{sessionId}}"
  width="100%"
  height="600">
</iframe>

4. Monitor the Session

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

Session Object

{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "referenceId": "USER12345",
  "amount": 500.00,
  "status": "Completed",
  "statusDetails": "EFT0301"
}

Status Codes

Session Status Values

Status	StatusDetails	Description
`Initiated`	`EFT0101`	Session created, awaiting user start
`Completed`	`EFT0301`	Transaction scheduled, session fully completed
`Completed`	`EFT0302`	Bank account validated, awaiting PAD signature
`Failed`	`EFT0401`	Login failed - invalid financial institution credentials
`Failed`	`EFT0402`	Eligibility failed - no guaranteed EFT offered
`Failed`	`EFT0403`	Identity failed - invalid user information verification
`Canceled`	`EFT0501`	Session canceled by API request
`Expired`	`EFT0601`	Session timed out - user inactive or did not complete

Status Meanings

EFT0101 - Session Created: A SessionId has been created and Flinks is awaiting for the user to start the session. EFT0301 - Transaction Scheduled: The user has successfully completed the session and a transaction schedule has been instructed. User is fully complete - transaction information can be checked for status of the schedule. This relates to an EFT transaction being instructed. EFT0302 - Bank Account Validated: The user has successfully validated their account (if required) - however, Flinks is awaiting the user to sign the PAD. EFT0401 - Login Failed: The user was not able to successfully login to their Financial Institution (received an invalid login). EFT0402 - Eligibility Failed: The user was not offered a Guaranteed EFT because of their account information (for example NSF or overall risk). Refer to reconciliation or the /Guarantees endpoint for more information. EFT0403 - Identity Failed: Invalid user information from their Financial Institution did not match provided user information, hence the session has failed. EFT0501 - Session Canceled: A call to the /Sessions/Cancel endpoint was made with the associated SessionId. EFT0601 - Session Timed Out: The sessionId timed-out before the user completed the session.

Field Specifications

Character Limits

Field	Limit	Notes
`firstName`, `lastName`	100 characters	Required for identity matching
`email`	100 characters	Used for notifications
`phone`	15 characters	Numbers only, no special characters
`referenceId`	100 characters	Strongly recommended for tracking
`addressLine1`	100 characters	Street address
`city`	100 characters	Full city name
`postalCode`	6 characters	No spaces (e.g., M5V0T7)
`province`	2 characters	Provincial code (e.g., ON, QC)
`country`	2 characters	Only “CA” supported
`accountNumber`	Between 7 and 12 characters	Numbers only
`transitNumber`	5 characters	Numbers only
`institutionCode`	3 characters	Numbers only

Validation Rules

Amount:

Maximum: $99,999.99 (default)
Minimum: Client-configurable
Decimal places: Up to 2

Currency:

Only “CAD” supported

Province Codes:

AB (Alberta), BC (British Columbia), MB (Manitoba)
NB (New Brunswick), NL (Newfoundland and Labrador)
NT (Northwest Territories), NS (Nova Scotia), NU (Nunavut)
ON (Ontario), PE (Prince Edward Island), QC (Quebec)
SK (Saskatchewan), YT (Yukon)

Phone Numbers:

Numbers only
No country codes, spaces, or special characters
Example: “5551234567” (not “+1-555-123-4567”)

Payment Processing

EFT Processing Windows

GEFT follows Payments Canada EFT processing schedule:

Window	Cutoff Time	Submission Time	Days
Window 1	2:30am EDT	9:30am EDT	Mon-Fri
Window 2	1:30pm EDT	4:30pm EDT	Mon-Fri
Window 3	6:00pm EDT	9:00pm EDT	Mon-Fri

Weekend/Holiday Processing: No processing on weekends or holidays. Settlement Timeline: Payments created before a cutoff are delivered approximately 2 hours after the next submission window.

Destination Account Logic

GEFT supports flexible destination account routing:

With payee object: Funds settle to specified account
Without payee object: Funds settle to your configured default account
No payee + no default: Request rejected with error

Payment Instructions

When a guarantee is accepted, Flinks issues:

EFT credit from Flinks float account to your destination account
EFT debit from end-user’s account to Flinks float account

The EFT credit to your account is the key status for settlement confirmation.

Frontend Integration

iFrame URL Pattern

{{BaseUri}}/app/?sessionId={{sessionId}}

Event Monitoring

window.addEventListener('message', function(e) {
  console.log('GEFT Event:', e.data);

  if (e.data.Step === 'SUCCESS') {
    // Payment completed successfully
  } else if (e.data.Step === 'GUARANTEE_FAILED') {
    // Guarantee declined, offer alternatives
  }
});

Error Handling

API Errors

Authentication Failed:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Invalid Request:

{
  "error": "invalid_request",
  "error_description": "Missing required field: firstName"
}

Session Not Found:

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

Common Integration Issues

Token Expiration: Access tokens expire after 599 seconds
Name Mismatch: User info must match bank account holder
Amount Limits: Respect min/max amount configurations
Character Limits: Validate field lengths before submission

Rate Limits

API endpoints have the following rate limits:

Authentication: 60 requests per minute
Session Creation: 100 requests per minute
Status Queries: 1000 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1647360000

Testing

Use the sandbox environment for integration testing:

Test Scenarios: Happy1, Happy2, Happy3, Unhappy1, Unhappy7, Unhappy8
Credentials: Provided during onboarding
Test Data: Predefined user profiles and expected outcomes

See Sandbox Guide for complete testing procedures.

Support

Technical Support:

Contact your Technical Account Manager
Reference session IDs and timestamps in support requests
Include relevant API request/response data

Documentation:

Next Steps

Authentication: Set up API authentication
Session Creation: Create and manage sessions
Setup Guide: Complete implementation walkthrough

API Reference

Auth

Connect

Enrich

Outbound

Pay

Upload

Utilities

Base URLs

Authentication

API Endpoints

Authentication

Session Management

Quick Start

1. Authenticate

2. Create Session

3. Launch User Flow

4. Monitor the Session

Session Object

Status Codes

Session Status Values

Status Meanings

Field Specifications

Character Limits

Validation Rules

Payment Processing

EFT Processing Windows

Destination Account Logic

Payment Instructions

Frontend Integration

iFrame URL Pattern

Event Monitoring

Error Handling

API Errors

Common Integration Issues

Rate Limits

Testing

Support

Next Steps

​Base URLs

​Authentication

​API Endpoints

​Authentication

​Session Management

​Quick Start

​1. Authenticate

​2. Create Session

​3. Launch User Flow

​4. Monitor the Session

​Session Object

​Status Codes

​Session Status Values

​Status Meanings

​Field Specifications

​Character Limits

​Validation Rules

​Payment Processing

​EFT Processing Windows

​Destination Account Logic

​Payment Instructions

​Frontend Integration

​iFrame URL Pattern

​Event Monitoring

​Error Handling

​API Errors

​Common Integration Issues

​Rate Limits

​Testing

​Support

​Next Steps

Base URLs

Authentication

API Endpoints

Authentication

Session Management

Quick Start

1. Authenticate

2. Create Session

3. Launch User Flow

4. Monitor the Session

Session Object

Status Codes

Session Status Values

Status Meanings

Field Specifications

Character Limits

Validation Rules

Payment Processing

EFT Processing Windows

Destination Account Logic

Payment Instructions

Frontend Integration

iFrame URL Pattern

Event Monitoring

Error Handling

API Errors

Common Integration Issues

Rate Limits

Testing

Support

Next Steps