Set Up Flinks Pay Using GEFT as the Payment Method

Complete the following steps to set up Flinks Pay using GEFT:

Complete the standard Flinks Pay onboarding process and verification.
Meet applicable MSB requirements and receive service approval from your dedicated Relationship Manager.
Receive your production GEFT credentials (Username/Client ID and Password/Client Secret) and base URI.
Configure your GEFT integration following the steps below.
Implement session creation using the /api/v2/sessions endpoint for each payment request.
Track user progress through the payment flow using:
- Frontend event listeners for real-time updates
- Status polling via /api/v2/sessions//status
- Webhook notifications for terminal status changes
Test your integration thoroughly using the Sandbox Guide.
Go to production with your dedicated Technical Account Manager support.

After your customer completes the GEFT flow, Flinks handles the guaranteed payment processing and settlement to your configured account.

Step 1: Authentication

All GEFT API requests that require authentication use an API key passed in the x-api-key header. Your API key will be provided during onboarding.

Headers

Header	Value	Description
`x-api-key`	Your API key	Required for authenticated endpoints
`x-client-id`	Your client ID	Identifies your client account
`Content-Type`	`application/json`	Required for request bodies

Step 2: Create Session

Endpoint

POST https://payments.flinksapp.com/api/v2/sessions

Required Fields

Field	Type	Description
`type`	String	Must be “EFT” for GEFT
`direction`	String	Must be “DEBIT” for GEFT
`options.guarantee.enable`	Boolean	Must be `true` for GEFT
`payor.firstName`	String	User’s first name (100 char limit)
`payor.lastName`	String	User’s last name (100 char limit)

Optional Fields

Field	Type	Description
`referenceId`	String	Your internal reference (100 char limit, strongly recommended)
`amount`	Decimal	Payment amount (up to $100,000, configurable per client)
`currency`	String	”CAD” (default)
`payor.email`	String	Email address (100 char limit)
`payor.address`	Object	Address information
`payee.account`	Object	Destination account details
`notificationPreferences.language`	String	”EN” or “FR”

Example Request

curl --location 'https://payments.flinksapp.com/api/v2/sessions' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{your_api_key}}' \
--header 'x-client-id: {{your_client_id}}' \
--data-raw '{
  "referenceId": "USER12345",
  "type": "EFT",
  "direction": "DEBIT",
  "currency": "CAD",
  "amount": 500.00,
  "options": {
    "guarantee": {
      "enable": true
    },
    "notificationPreferences": {
      "language": "EN"
    }
  },
  "payor": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",    
    "address": {
      "addressLine1": "123 Main Street",
      "city": "Toronto",
      "postalCode": "M5V3A8",
      "province": "ON",
      "country": "CA"
    }
  },
  "payee": {
    "account": {
      "accountNumber": "12345678",
      "transitNumber": "12345",
      "institutionCode": "999"
    }
  }
}'

Response

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

Step 3: Launch iFrame

Once you have a sessionId, launch the GEFT user flow:

<iframe
  src="https://payments.flinksapp.com/app/?sessionId={{sessionId}}"
  width="100%"
  height="600">
</iframe>

Event Listening

Monitor frontend events to track user progress:

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

  switch(e.data.step) {
    case 'APP_INITIATED':
      console.log('Payment flow initiated');
      break;
    case 'INSTITUTION_SELECTED':
      console.log('User selected bank');
      break;
    case 'GUARANTEE_OFFERED':
      console.log('Payment can be guaranteed');
      break;
    case 'SUCCESS':
      console.log('Payment completed successfully');
      break;
    case 'GUARANTEE_FAILED':
      console.log('Guarantee declined');
      break;
  }
});
</script>

Step 4: Monitor Session Status

Endpoint

GET https://payments.flinksapp.com/api/v2/sessions/{{sessionId}}/status

Example Request

curl --location 'https://payments.flinksapp.com/api/v2/sessions/{{sessionId}}/status'

Response

{
  "sessionId": "aadd08f2-83ce-456d-84ed-c68cfed4ee7b",
  "referenceId": "USER12345",
  "amount": 500,
  "status": "Completed",
  "statusDetails": "EFT0301"
}

Status Codes

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 credentials
Failed	EFT0402	Eligibility failed - no guarantee offered
Failed	EFT0403	Identity failed - user info mismatch
Canceled	EFT0501	Session canceled by API request
Expired	EFT0601	Session timed out

Step 5: Handle Completion

Successful Completion (EFT0301)

When status is “Completed” with “EFT0301”:

Payment is guaranteed and scheduled
Funds will be settled according to EFT processing windows
No further action required

Failed Scenarios

Guarantee Declined (EFT0402)

Offer alternative payment methods
Transaction cannot proceed with GEFT

Identity Mismatch (EFT0403)

User information doesn’t match bank account
Session must be terminated

User Cancellation

User exited flow without completing
Can retry with new session

Destination Account Logic

GEFT supports routing payments to different accounts:

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

Important Implementation Notes

User Identity Matching

firstName and lastName must accurately reflect the bank account owner
Significant name differences will cause session failure (EFT0403)
Identity validation occurs after account connection

Reference ID Best Practices

Use unique identifier for each transaction
Include in reconciliation and support requests
Appears in all status responses and reconciliation files

Amount Handling

If amount provided: User cannot modify, “Enter amount” step is grayed out
If amount omitted: User enters amount in flow
Min/max limits configured at client level by Flinks

Character Limits

Names: 255 characters
Email: 256 characters
Reference ID: 100 characters
Country: 2 characters (ISO country code)
Account Number: 7 to 12 digits
Transit Number: 5 digits
Institution Code: 3 digits

Error Handling

// Handle session status polling
async function pollSessionStatus(sessionId) {
  const maxAttempts = 20;
  const pollInterval = 30000; // 30 seconds

  for (let i = 0; i < maxAttempts; i++) {
    try {
      const response = await fetch(
        `https://payments.flinksapp.com/api/v2/sessions/${sessionId}/status`
      );

      const status = await response.json();

      // Check for terminal states
      if (['Completed', 'Failed', 'Canceled', 'Expired'].includes(status.status)) {
        return status;
      }

      // Wait before next poll
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    } catch (error) {
      console.error('Status polling error:', error);
    }
  }

  throw new Error('Polling timeout - session status unknown');
}

Next Steps

Event Handling: Implement comprehensive event tracking
Sandbox Guide: Test your integration
API Reference: Complete API documentation

Testing Your Integration

Use the sandbox environment with test scenarios:

Happy1: Successful flow
Happy2: Next-best-offer scenario
Unhappy1: Guarantee failure

See the Sandbox Guide for complete testing procedures.

Getting Started

AI

Connect

Enrich

Pay

Webhooks

Upload

Dashboard

Outbound

Security

Support

Set Up Flinks Pay Using GEFT as the Payment Method

Step 1: Authentication

Headers

Step 2: Create Session

Endpoint

Required Fields

Optional Fields

Example Request

Response

Step 3: Launch iFrame

Event Listening

Step 4: Monitor Session Status

Endpoint

Example Request

Response

Status Codes

Step 5: Handle Completion

Successful Completion (EFT0301)

Failed Scenarios

Destination Account Logic

Important Implementation Notes

User Identity Matching

Reference ID Best Practices

Amount Handling

Character Limits

Error Handling

Next Steps

Testing Your Integration

​Step 1: Authentication

​Headers

​Step 2: Create Session

​Endpoint

​Required Fields

​Optional Fields

​Example Request

​Response

​Step 3: Launch iFrame

​Event Listening

​Step 4: Monitor Session Status

​Endpoint

​Example Request

​Response

​Status Codes

​Step 5: Handle Completion

​Successful Completion (EFT0301)

​Failed Scenarios

​Destination Account Logic

​Important Implementation Notes

​User Identity Matching

​Reference ID Best Practices

​Amount Handling

​Character Limits

​Error Handling

​Next Steps

​Testing Your Integration

Step 1: Authentication

Headers

Step 2: Create Session

Endpoint

Required Fields

Optional Fields

Example Request

Response

Step 3: Launch iFrame

Event Listening

Step 4: Monitor Session Status

Endpoint

Example Request

Response

Status Codes

Step 5: Handle Completion

Successful Completion (EFT0301)

Failed Scenarios

Destination Account Logic

Important Implementation Notes

User Identity Matching

Reference ID Best Practices

Amount Handling

Character Limits

Error Handling

Next Steps

Testing Your Integration