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

# Set Up Flinks Pay Using GEFT as the Payment Method

> Configure Flinks Pay with GEFT from onboarding and authentication through to production.

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](/api/pay/endpoints/geft/sessions-initiate) 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/{sessionId}/status](/api/pay/endpoints/geft/sessions-status)
   * Webhook notifications for terminal status changes
7. Test your integration thoroughly using the [Sandbox Guide](/guides/pay/geft/sandbox-overview).
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

| 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

```bash theme={null}
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

```json theme={null}
{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "referenceId": "USER12345"
}
```

## Step 3: Launch iFrame

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

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

### Event Listening

Monitor frontend events to track user progress:

```html theme={null}
<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

```bash theme={null}
curl --location 'https://payments.flinksapp.com/api/v2/sessions/{{sessionId}}/status'
```

### Response

```json theme={null}
{
  "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

```javascript theme={null}
// 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](/guides/pay/geft/event-handling)**: Implement comprehensive event tracking
2. **[Sandbox Guide](/guides/pay/geft/sandbox-overview)**: Test your integration
3. **[API Reference](/api/pay/endpoints/geft/index)**: 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](/guides/pay/geft/sandbox-overview) for complete testing procedures.