Documentation Index
Fetch the complete documentation index at: https://docs.flinks.com/llms.txt
Use this file to discover all available pages before exploring further.
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.
| 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_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
| 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–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.
