> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interac e-Transfer

> Initialize Interac e-Transfer payments for Canadian transactions

## Overview

Interac e-Transfer enables secure money transfers between Canadian bank accounts. This endpoint supports both incoming (receiving) and outgoing (sending) transfers.

## Endpoint

```bash theme={null}
POST /payment-sessions
```

## Common Requirements

<Card>
  **Canadian-Specific Validation:**

  * Valid Canadian phone number (+1 format)
  * Canadian postal code format
  * Province/territory codes (e.g., ON, BC, AB)
  * Canadian bank account required
</Card>

<Accordion title=" Incoming Payments (CAD via Interac Auto-Deposit)" icon="sparkles">
  ## **Incoming Payments (CAD via Interac Auto-Deposit)** 

  CAD direct deposits via **Interac Auto-Deposit** streamline the payment process, ensuring that incoming funds are quickly and securely credited to your account, enhancing both convenience and financial management.

  <Check>
    Auto-deposit is enabled using the **merchant’s registered email**. Once we receive the merchant’s registered email, we configure it for Interac Auto-Deposit.
  </Check>

  <Tip>
    Test incoming CAD deposits in **Production**, as deposits are real-time.
  </Tip>

  ### **Confirming Deposits**

  To confirm incoming deposits, listen for webhooks.

  **Example webhook payload (successful CAD deposit):**

  ```json theme={null}

  {

    "checksum": "",

    "data": {

      "amount": 10000,

      "callback_urls": {},

      "cancellation_reason": null,

      "channel_reference": "",

      "collection_mode": null,

      "correlation_id": "",

      "currency": "NGN",

      "customer": {

        "account_id": "",

        "billing_address": {

          "city": "",

          "country": "NG",

          "line1": "",

          "state": "",

          "zip_code": ""

        },

        "email": "",

        "first_name": "",

        "id": "",

        "last_name": "",

        "phone_number": "",

        "type": ""

      },

      "date": "",

      "description": "",

      "fee": null,

      "id": "",

      "merchant": {

        "address": {

          "city": "",

          "country": "NG",

          "line1": "",

          "line2": null,

          "state": "",

          "zip_code": ""

        },

        "email": "",

        "id": "",

        "mcc": "",

        "name": "",

        "phone": ""

      },

      "order": {

        "identifier": "",

        "items": [

          {

            "name": "Transfer",

            "type": "digital"

          }

        ]

      }

      "mode": "live",

      "order": {

        "identifier": "",

        "items": [

          {

            "name": "Transfer",

            "type": "digital"

          }

        ]

      },

      "payer": {

        "account_name": null,

        "account_number": null,

        "bank_name": ""

      },

      "payment_method": {

        "account_numner": "",

        "account_name": "",

        "bank_code": "",

        "bank_name": "",

        "currency": "",

        "id": "",

        "type": "bank_account"

      },

      "provider_id": "",

      "redirect_url": null,

      "reference": "",

      "status": "success|failed",

      "transaction_id": "",

      "type": "payin|payout"

    },

    "event": "payment.session.succeeded|payment.session.failed"




  }
  ```

  <Check>
    **Developer tasks:**

    * Provide the merchant’s **registered email** so it can be enabled for auto-deposit.
    * Implement an endpoint on your server to receive POST requests from Juicyway.
    * Verify the checksum for authenticity.
    * Use status (success) + type (payin) to confirm the CAD deposit.
    * Update your internal systems (balances, invoices, etc.).
  </Check>
</Accordion>

<Accordion title="Incoming via Interac link" icon="sparkles">
  ## Overview

  Capture an Interac e-Transfer payment by generating a secure payment link that your customer can use to complete the transfer. This endpoint supports incoming (receiving) payments through Canada's Interac e-Transfer system.

  <Note>
    Interac e-Transfer is only available for Canadian dollar (CAD) transactions and requires both the sender and recipient to have Canadian bank accounts.
  </Note>

  ## Endpoint

  ```bash theme={null}
  POST /payment-sessions/{payment_id}
  ```

  ## Capture Flow

  <Steps>
    <Step title="Initialize Payment">
      First create a payment session with [payment initialization](/payments/initialize-payment/interac-e-transfer)
    </Step>

    <Step title="Generate Transfer Link">
      Capture the payment to generate an Interac e-Transfer link
    </Step>

    <Step title="Customer Transfer">
      Customer completes the transfer through their online banking
    </Step>

    <Step title="Auto-Deposit">
      Funds are automatically deposited if enabled, or require security answer
    </Step>
  </Steps>

  ## Response Object

  ```json theme={null}
  {
    "data": {
      "auth_type": null,
      "expires_at": "2024-04-09T01:11:30.239705Z",
      "links": {
        "redirect_url": "https://gateway-web.fit.interac.ca/reqPayment/eml/CA1MRz75R4Hy"
      },
      "message": "Waiting for payment",
      "payment": {
        "amount": 100000,  // Amount in cents
        "currency": "CAD",
        "status": "pending",
        "payment_method": {
          "type": "interac"
        },
        "customer": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone_number": "+14165555555",
          "billing_address": {
            "line1": "123 Main St",
            "line2": "Unit 4B",
            "city": "Toronto",
            "state": "ON",
            "country": "CA",
            "zip_code": "M5V 2T6"
          }
        },
        "description": "Invoice payment",
        "reference": "inv_20240322_123",
        "order": {
          "identifier": "ORD12345",
          "items": [
            {
              "name": "Professional Services",
              "type": "service"
            }
          ]
        }
      }
    }
  }
  ```

  ### Important Response Fields

  <ResponseField name="links.redirect_url" type="string" required>
    Interac e-Transfer payment link to share with customer

    * Valid for payment session duration
    * Unique per transaction
    * Must be accessed within expires\_at time
  </ResponseField>

  <ResponseField name="expires_at" type="string" required>
    ISO 8601 timestamp when the payment session expires

    * Default: 1 hours from creation
    * Customer must complete transfer before this time
  </ResponseField>

  ##
</Accordion>

<Accordion title="Outgoing transfers" icon="sparkles">
  ##

  ## Outgoing Transfers

  <Note>
    Use this flow when sending payments to recipients through Interac e-Transfer.
  </Note>

  ### Additional Parameters for Outgoing Transfers

  <ParamField body="payment_method" type="object" required>
    <Expandable title="Payment Method">
      <ParamField body="beneficiary_type" type="string" required>
        One of: "personal", "business"
      </ParamField>

      <ParamField body="first_name" type="string" required>
        Recipient's first name
      </ParamField>

      <ParamField body="last_name" type="string" required>
        Recipient's last name
      </ParamField>

      <ParamField body="email" type="string" required>
        Recipient's Interac-registered email
      </ParamField>

      <ParamField body="phone_number" type="string">
        Recipient's phone number (optional)
      </ParamField>

      <ParamField body="question" type="string" required>
        Security question for the transfer
      </ParamField>

      <ParamField body="answer" type="string" required>
        Answer to the security question
      </ParamField>
    </Expandable>
  </ParamField>

  ### Example Request (Outgoing)

  ```json theme={null}
  {
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_number": "+14165555555",
      "billing_address": {
        "line1": "123 Main St",
        "line2": "Unit 4B",
        "city": "Toronto",
        "state": "ON",
        "country": "CA",
        "zip_code": "M5V 2T6"
      },
      "ip_address": "127.0.0.1"
    },
    "description": "Expense reimbursement",
    "currency": "CAD",
    "amount": 100000,
    "direction": "outgoing",
    "payment_method": {
      "type": "interac",
      "beneficiary_type": "personal",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "phone_number": "+14165556666",
      "question": "What is our project code",
      "answer": "ALPHA123"
    },
    "reference": "exp_20240322_456",
    "order": {
        "identifier": "EXP12345",
        "items": [
          {
            "name": "Travel Reimbursement",
            "type": "expense"
          }
        ]
    },
  }
  ```

  ##
</Accordion>

<Accordion title="Link email to customer " icon="sparkles">
  ## **Linking Multiple Emails**

  In situations where a user has multiple email addresses, we typically advise applying restrictions. However, when necessary, you can link a secondary email (Email 2) to the primary registered email (Email 1) using the endpoint below.

  **Endpoint:**

  ```bash theme={null}
  PATCH /customers/:id/register_emails
  ```

  **Request Body:**

  ```json theme={null}

  {

    "emails": [

      "user1@example.com",   // primary registered email (Email 1)

      "user2@example.com"    // additional linked email (Email 2)

    ]

  }
  ```
</Accordion>

Validation Rules

<AccordionGroup>
  <Accordion title="Amount Validation">
    * Minimum: CAD 100.00 (10000 cents)
    * Maximum: CAD 10,000.00 (1000000 cents)
    * Must be in Canadian Dollars (CAD)
    * Must be a positive integer in cents
  </Accordion>

  <Accordion title="Phone Number Validation">
    * Must begin with +1
    * Must be 11 digits total (+1 plus 10-digit number)
    * Area code must be valid for Canada
  </Accordion>

  <Accordion title="Postal Code Validation">
    * Must follow Canadian format: "A1A 1A1"
    * Letter-number-letter number-letter-number
    * First letter cannot be D, F, I, O, Q, U, W, Z
  </Accordion>

  <Accordion title="Security Question">
    * Required for outgoing transfers
    * Question must be 10-100 characters
    * Answer must be 3-50 characters
    * Cannot contain sensitive information
  </Accordion>
</AccordionGroup>

## Error Handling

<ResponseField name="invalid_province" type="error">
  Invalid Canadian province/territory code provided.

  * Must be one of: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT
</ResponseField>

<ResponseField name="invalid_postal_code" type="error">
  Invalid Canadian postal code format.

  * Must match pattern: A1A 1A1
</ResponseField>

<ResponseField name="invalid_phone" type="error">
  Invalid Canadian phone number.

  * Must start with +1
  * Must be a valid area code
</ResponseField>

<ResponseField name="amount_limit_exceeded" type="error">
  Transfer amount exceeds limits.

  * Check minimum/maximum allowed amounts
</ResponseField>

## Processing Times

<Note>
  * Incoming transfers: Usually processed within 15-30 minutes
  * Outgoing transfers: Usually processed within 30-60 minutes
  * Cutoff times may apply based on recipient's bank
</Note>

<Card title="Need Help?">
  For support with Interac e-Transfer integration:

  * Check our [Error Handling Guide](/errors)
  * Contact [Support](mailto:support@juicyway.com)
</Card>