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

# EFT V2 API Overview

> API reference for EFT (Electronic Funds Transfer) payments — V2, session-based

<Warning>
  **Work in progress**

  This section is currently under active development as part of improvements planned for 2026. Content may change as we expand product capabilities.

  If you're interested in early access or want to learn more about what's coming, feel free to [reach out to the team](/guides/support/contact-flinks).
</Warning>

EFT **V2** replaces V1's endpoint-by-endpoint integration with a single **session-based** flow. You create one session, launch the hosted Flinks Pay experience, and monitor the session to completion — no custom front-end required.

<Note>
  Looking for the original endpoints (create transaction, schedules, PAD agreements)? See the [EFT V1 reference](/api/pay/endpoints/eft/index). V2 is the recommended path for new integrations.
</Note>

## How V2 differs from V1

|                      | V1 (Direct Transactions)             | V2 (Session-based)                     |
| -------------------- | ------------------------------------ | -------------------------------------- |
| Integration          | Multiple endpoints, custom front-end | One session + hosted UI                |
| Create call          | `POST /api/v1/transactions`          | `POST /api/v2/sessions` (`type = EFT`) |
| Status model         | `EftStatus` / `PaymentStatus`        | `SessionStatus`                        |
| Bank account capture | Provided by you                      | Captured in the hosted flow            |

This is the **Regular EFT path**. Guarantee features belong to the [GEFT product](/api/pay/endpoints/geft/index).

## Base URLs

**Production:** `{{BaseUri}}`
**Sandbox:** `{{BaseUri}}`

## Authentication

EFT V2 uses the OAuth 2.0 Client Credentials flow:

1. **Authenticate** with Basic auth (Client ID and Secret) at the [/Authorize](/api/pay/endpoints/authorize/authorize) endpoint.
2. **Receive** a Bearer token valid for 599 seconds (10 minutes).
3. **Use** the Bearer token on all subsequent calls via the `Authorization: Bearer` header.
4. **Refresh** the token before it expires.

| Endpoint                                   | Authentication |
| ------------------------------------------ | -------------- |
| `POST /api/v2/sessions`                    | Bearer token   |
| `POST /api/v2/sessions/{sessionId}/cancel` | Bearer token   |
| `GET /api/v2/sessions/{sessionId}/details` | Bearer token   |

Session creation requires the **RegularEft** feature to be enabled on your client (otherwise the request returns `403`).

## API Endpoints

| Method | Endpoint                               | Description                                                       |
| ------ | -------------------------------------- | ----------------------------------------------------------------- |
| POST   | `/api/v1/authorize`                    | [Obtain access token](/api/pay/endpoints/authorize/authorize)     |
| POST   | `/api/v2/sessions`                     | [Initiate session](/api/pay/endpoints/eft/v2/sessions-initiate)   |
| GET    | `/api/v2/sessions/{sessionId}/details` | [Get session details](/api/pay/endpoints/eft/v2/sessions-details) |
| POST   | `/api/v2/sessions/{sessionId}/cancel`  | [Cancel session](/api/pay/endpoints/eft/v2/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 {{clientId:clientSecret}}' \
--data-urlencode 'grant_type=client_credentials'
```

### 2. Initiate a 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",
  "payor": {
    "firstName": "Sara",
    "lastName": "Ahmad",
    "email": "sara.ahmad@example.com"
  },
  "options": {
    "guarantee": { "enable": false }
  }
}'
```

The response returns a `sessionId`:

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

### 3. Launch the user flow

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

### 4. Monitor the session

```bash theme={null}
curl --location '{{BaseUri}}/api/v2/sessions/{{sessionId}}/details' \
--header 'Authorization: Bearer {{access_token}}'
```

## Session 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 financial institution credentials          |
| `Failed`    | `EFT0403`     | 🔴 Identity failed — user information did not match the bank account |
| `Failed`    | `EFT0404`     | 🔴 Insufficient available balance                                    |
| `Cancelled` | `EFT0501`     | ⚫ Session cancelled by API request                                   |
| `Expired`   | `EFT0601`     | ⚫ Session timed out — user inactive or did not complete              |

<Note>
  Guarantee-related outcomes do not apply to regular EFT — they are specific to [GEFT](/api/pay/endpoints/geft/index).
</Note>

## Validation Rules

* `type` must be `EFT`; `direction` must be `DEBIT`; `currency` must be `CAD` (defaults to `CAD`).
* `payor.firstName`, `payor.lastName`, and `payor.email` are **required**.
* `payor.address` is **optional** for regular EFT. If provided, address line 1, city, province, postal code, and country are required.
* `payee` must be **omitted** — funds settle to your client's configured account.
* `referenceId` is optional but recommended; it must be 1–36 alphanumeric characters or hyphens.
* `amount` is optional; if provided it must be greater than 0, have at most 2 decimal places, and fall within your client's configured minimum/maximum EFT amount. If omitted, the user enters the amount in the hosted flow.

## Next Steps

1. **[Initiate Session](/api/pay/endpoints/eft/v2/sessions-initiate)** — full request and response schema
2. **[Session Details](/api/pay/endpoints/eft/v2/sessions-details)** — retrieve full session information and status