Skip to main content
Complete the following steps to set up Flinks Pay using GEFT:
  1. Complete the standard Flinks Pay onboarding process and verification.
  2. Meet applicable MSB requirements and receive service approval from your dedicated Relationship Manager.
  3. Receive your production GEFT credentials (Username/Client ID and Password/Client Secret) and base URI.
  4. Configure your GEFT integration following the steps below.
  5. Implement session creation using the /api/v2/sessions endpoint for each payment request.
  6. 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
  7. Test your integration thoroughly using the Sandbox Guide.
  8. 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

HeaderValueDescription
x-api-keyYour API keyRequired for authenticated endpoints
x-client-idYour client IDIdentifies your client account
Content-Typeapplication/jsonRequired for request bodies

​
Step 2: Create Session

​
Endpoint

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

​
Required Fields

FieldTypeDescription
typeStringMust be “EFT” for GEFT
directionStringMust be “DEBIT” for GEFT
options.guarantee.enableBooleanMust be true for GEFT
payor.firstNameStringUser’s first name (100 char limit)
payor.lastNameStringUser’s last name (100 char limit)

​
Optional Fields

FieldTypeDescription
referenceIdStringYour internal reference (100 char limit, strongly recommended)
amountDecimalPayment amount (up to $100,000, configurable per client)
currencyString”CAD” (default)
payor.emailStringEmail address (100 char limit)
payor.addressObjectAddress information
payee.accountObjectDestination account details
notificationPreferences.languageString”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_MOUNTED':
      console.log('GEFT app loaded');
      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

StatusStatusDetailsDescription
InitiatedEFT0101Session created, awaiting user start
CompletedEFT0301Transaction scheduled, session fully completed
CompletedEFT0302Bank account validated, awaiting PAD signature
FailedEFT0401Login failed - invalid credentials
FailedEFT0402Eligibility failed - no guarantee offered
FailedEFT0403Identity failed - user info mismatch
CanceledEFT0501Session canceled by API request
ExpiredEFT0601Session 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–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

  1. Event Handling: Implement comprehensive event tracking
  2. Sandbox Guide: Test your integration
  3. 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.