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

# E-Transfer API Overview

> Complete API reference for Interac e-Transfer (Request For Money) payments

The Flinks Interac (e-Transfer) API lets you initiate a Request For Money (RFM) session and collect payments from end users through Interac e-Transfer. This reference covers the endpoints needed to create a session and retrieve its details.

## Base URL

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

## Authentication

All e-Transfer 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`                     | [Initiate e-Transfer session](/api/pay/endpoints/e-transfer/sessions-initiate) |
| GET    | `/api/v2/sessions/{sessionId}/details` | [Get session details](/api/pay/endpoints/e-transfer/sessions-details)          |

## 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. Initiate 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": "e-Transfer",
  "direction": "CREDIT",
  "currency": "CAD",
  "amount": 250.00,
  "options": {
    "notificationPreferences": {
      "language": "EN",
      "sendInteracLink": true
    }
  },
  "payor": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com"
  }
}'
```

### 3. Launch User Flow

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

### 4. Retrieve Session Details

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

## Session Object

```json theme={null}
{
  "sessionId": "850750a4-3021-4061-ac03-a8d873aa4179",
  "referenceId": "USER12345",
  "status": "Completed",
  "type": "e-Transfer",
  "direction": "CREDIT",
  "currency": "CAD",
  "amount": 250.00
}
```

## Session Statuses

| Status      | Description                                           |
| ----------- | ----------------------------------------------------- |
| `Initiated` | Session created, awaiting user action                 |
| `Completed` | User has successfully completed the flow              |
| `Failed`    | Session failed (for example, identity or eligibility) |
| `Cancelled` | Session was cancelled                                 |
| `Expired`   | Session timed out before completion                   |

## Field Specifications

### Character Limits

| Field                                 | Limit           | Notes                                    |
| ------------------------------------- | --------------- | ---------------------------------------- |
| `firstName`, `lastName`, `middleName` | 100 characters  | Required for identity matching           |
| `email`                               | 100 characters  | Used for notifications and link delivery |
| `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`                       | 7–12 characters | Numbers only                             |
| `transitNumber`                       | 5 characters    | Numbers only                             |
| `institutionCode`                     | 3 characters    | Numbers only                             |

### Validation Rules

**Amount**

* Up to 2 decimal places
* Minimum and maximum are client-configurable via session `options.limits`

**Currency**

* Only `CAD` is supported

**Payment Type**

* `e-Transfer` for Interac e-Transfer sessions
* `EFT` for EFT sessions

**Payment Direction**

* `CREDIT` — funds flow to the payee
* `DEBIT` — funds flow from the payor

## Notification Preferences

Control how the end user is notified of the request:

* `language` — `EN` or `FR`
* `sendInteracLink` — when `true`, Flinks sends the Interac e-Transfer request link directly to `payor.email`. When `false`, you distribute the hosted app URL yourself.

## Frontend Integration

### iFrame URL Pattern

```
{{BaseUri}}/app/?sessionId={{sessionId}}
```

### Event Monitoring

```javascript theme={null}
window.addEventListener('message', function(e) {
  console.log('e-Transfer Event:', e.data);

  if (e.data.Step === 'SUCCESS') {
    // Session completed successfully
  } else if (e.data.Step === 'EXIT') {
    // User exited the flow
  }
});
```

## Error Handling

Error responses follow the RFC 7807 `ProblemDetails` format:

```json theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Missing required field: payor.firstName"
}
```

**Common HTTP status codes**

| Status | Meaning                         |
| ------ | ------------------------------- |
| 201    | Session created                 |
| 200    | Request succeeded               |
| 400    | Invalid request payload         |
| 401    | Missing or invalid access token |
| 403    | Access denied                   |

## Next Steps

1. **[Authentication](/api/pay/endpoints/authorize/authorize)** — obtain an access token
2. **[Initiate Session](/api/pay/endpoints/e-transfer/sessions-initiate)** — create an e-Transfer session
3. **[Session Details](/api/pay/endpoints/e-transfer/sessions-details)** — retrieve session information
4. **[Setup Guide](/guides/pay/e-transfer/setup-flinks-pay)** — complete implementation walkthrough