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

# GEFT API Overview

> Complete API reference for GEFT (Guaranteed Electronic Funds Transfer) payments

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:

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

## API Endpoints

### Authentication

| Method | Endpoint            | Description                                                   |
| ------ | ------------------- | ------------------------------------------------------------- |
| POST   | `/api/v1/authorize` | [Obtain access token](/api/pay/endpoints/authorize/authorize) |

### Session Management

| Method | Endpoint                                          | Description                                                             |
| ------ | ------------------------------------------------- | ----------------------------------------------------------------------- |
| POST   | `/api/v2/sessions`                                | [Create GEFT session](/api/pay/endpoints/geft/sessions-initiate)        |
| GET    | `/api/v2/sessions/{sessionId}/status`             | [Get session status](/api/pay/endpoints/geft/sessions-status)           |
| GET    | `/api/v2/sessions/{sessionId}/details`            | [Get session details](/api/pay/endpoints/geft/sessions-details)         |
| POST   | `/api/v2/sessions/{sessionId}/guarantees/confirm` | [Confirm Guarantee Decision](/api/pay/endpoints/geft/guarantee-confirm) |
| POST   | `/api/v2/sessions/{sessionId}/cancel`             | [Cancel session](/api/pay/endpoints/geft/sessions-cancel)               |

## Quick Start

### 1. Authenticate

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

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

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

### 4. Monitor Status

```bash theme={null}
curl --location '{{BaseUri}}/api/v2/sessions/{{sessionId}}/status' \
```

## Session Object

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

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

### Payment Instructions

When a guarantee is accepted, Flinks issues:

1. **EFT credit** from Flinks float account to your destination account
2. **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

```javascript theme={null}
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:**

```json theme={null}
{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}
```

**Invalid Request:**

```json theme={null}
{
  "error": "invalid_request",
  "error_description": "Missing required field: firstName"
}
```

**Session Not Found:**

```json theme={null}
{
  "error": "not_found",
  "error_description": "Session not found"
}
```

### Common Integration Issues

1. **Token Expiration**: Access tokens expire after 599 seconds
2. **Name Mismatch**: User info must match bank account holder
3. **Amount Limits**: Respect min/max amount configurations
4. **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](/guides/pay/geft/sandbox-overview) 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:**

* [Setup Guide](/guides/pay/geft/setup-flinks-pay)
* [Event Handling](/guides/pay/geft/event-handling)
* [Sandbox Guide](/guides/pay/geft/sandbox-overview)

## Next Steps

1. **[Authentication](/api/pay/endpoints/authorize/authorize)**: Set up API authentication
2. **[Session Creation](/api/pay/endpoints/geft/sessions-initiate)**: Create and manage sessions
3. **[Setup Guide](/guides/pay/geft/setup-flinks-pay)**: Complete implementation walkthrough