> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://interacdocs.nolimit.money/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://interacdocs.nolimit.money/_mcp/server.

# Developer FAQ

## Deposits, step by step

#### What happens during a deposit, from start to finish?

```mermaid
sequenceDiagram
    participant C as Customer
    participant P as Your platform
    participant N as NoLimit API
    participant I as Interac and customer's bank
    C->>P: Chooses an amount to deposit
    P->>N: POST /request (amount, payeeEmail, name, memo)
    N->>I: Creates an Interac money request
    N-->>P: 201 with transactionId, status, interacLink
    P->>C: Shows or redirects to interacLink
    C->>I: Opens the link, signs in to their bank, approves the payment
    I-->>N: Funds received
    N-->>P: Webhook with status COMPLETED
    P->>C: Credits the customer's account on your platform
```

1. **The customer chooses an amount** on your platform.
2. **Your backend calls [`POST /request`](/partner-interac-api/request-interac-deposit)** with the amount, the customer's email address and name, a memo, and a new `Idempotency-Key`.
3. **You get `201 Created`** with the `transactionId`, a `status` and the `interacLink`. Store the `transactionId` against your order.
4. **You send the customer to the `interacLink`.** This is the only way the customer reaches the payment. NoLimit doesn't email it to them.
5. **The customer pays on the Interac page.** They pick their bank, sign in to their online banking and approve the payment. Or they decline it.
6. **The money settles.** When it reaches NoLimit, the deposit becomes `COMPLETED`, your balance is credited, and your webhook is called.
7. **You credit the customer** on your platform.

#### What does the customer see?

1. On your site: the amount and a button or link to pay with Interac.
2. On the Interac page: a list of banks. The customer picks theirs.
3. In their online banking: the payment request, with the amount and the payee. They approve it, or decline it.
4. A confirmation from their bank.

The customer doesn't come back to your site automatically. The API has no return URL. Open the `interacLink` in a new tab or window, and keep your own page open with a "waiting for payment" status.

#### How should I build the deposit screen?

* Show the amount and a clear "Pay with Interac" button that opens the `interacLink` in a new tab.
* After the customer clicks it, show a waiting state: "Complete the payment in your online banking. This page updates when the payment arrives."
* Update the page from your backend when the webhook arrives, or by polling [`GET /request/{id}`](/partner-interac-api/look-up-deposit-request-by-transaction-id).
* Keep the `interacLink` available in the customer's account history until the deposit is final, so they can come back and pay later.
* Don't ask the customer to "upload proof of payment". A deposit completes only when the money reaches NoLimit.

#### Where do I get the interacLink, and what if it's missing?

It's in the `201` response of `POST /request`, and also in `GET /request/{id}`.

If the status is `INCOMPLETE`, there is no `interacLink`: Interac didn't accept the request, and the deposit has already failed. Create a new deposit with a new `Idempotency-Key`.

#### How long does the customer have to pay?

30 days. Until the customer pays or declines it, the deposit stays open, usually as `SENT`. After 30 days, Interac closes it and it fails.

Don't mark an unpaid deposit as failed on your side before you get a final status. The customer can still pay it.

#### The customer left without paying. What should I do?

The request is still valid. Send the customer back to the same `interacLink`, for example with a reminder after an hour and another after a day.

If they restart the deposit on your site for the same amount, reuse the original `Idempotency-Key`, or let the API return the open deposit. Don't create a new request. A customer can have only one open deposit at a time. A new request for a different amount is refused with `409 DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH` (see [`POST /request`](/partner-interac-api/request-interac-deposit) for the full explanation).

#### Can the customer change the amount, or can I cancel a deposit?

No to both. The amount is fixed when the request is created, and there is no endpoint to cancel a deposit. Only the customer can close it, by paying or declining it. For a different amount, the customer must decline the open request first.

#### How do I know the deposit is paid?

Wait for `COMPLETED`, either from your webhook or from `GET /request/{id}`. It usually arrives within a few minutes of the customer paying. It takes longer when the customer's bank holds the transfer for review.

Only `COMPLETED` means the money has arrived. Don't credit the customer on any other status.

## Withdrawals, step by step

#### What happens during a withdrawal, from start to finish?

```mermaid
sequenceDiagram
    participant C as Customer
    participant P as Your platform
    participant N as NoLimit API
    participant I as Interac and customer's bank
    C->>P: Requests a payout
    P->>N: POST /withdrawal (firstName, lastName, payoutEmail, memo, amount)
    N->>N: Debits your balance
    N->>I: Sends an Interac e-Transfer
    N-->>P: 201 with transactionId, status, securityQuestion, encrypted securityAnswer
    P->>C: Shows the security answer
    I->>C: Emails the customer that money is waiting
    C->>I: Opens the email, answers the security question, deposits the money
    I-->>N: Transfer accepted
    N-->>P: Webhook with status COMPLETED
```

1. **The customer requests a payout** on your platform.
2. **Your backend calls [`POST /withdrawal`](/partner-interac-api/send-interac)** with the customer's first and last name, email address, a memo, the amount and a new `Idempotency-Key`. You can also send your own `securityQuestion` and `securityAnswer`. If you don't, a pair is generated.
3. **Your balance is debited** by the amount straight away. If the balance is too low, you get `400 INSUFFICIENT_FUNDS` and nothing is sent.
4. **You get `201 Created`** with the `transactionId`, a `status`, the `securityQuestion` and an encrypted `securityAnswer`. Store the `transactionId` against the payout.
5. **You show the customer the security answer.** They need it to accept the money.
6. **Interac emails the customer** that money is waiting for them. The email comes from Interac, not from NoLimit or from you.
7. **The customer accepts the money.** They open the email, pick their bank, answer the security question and choose the account to deposit into.
8. **The withdrawal becomes `COMPLETED`**, and your webhook is called.

If the withdrawal fails instead (`INCOMPLETE`, `DECLINED`, `REJECTED` or `CANCELLED`), the amount is credited back to your balance.

#### What does the customer see?

1. On your site: confirmation that the payout was sent, the amount, and the **security answer**.
2. In their email: a message from Interac saying money is waiting for them.
3. On the Interac page or in their online banking: they pick their bank, enter the security answer and choose the account.
4. The money arrives in their bank account.

If the customer has Autodeposit set up with their bank, the money goes straight into their account, and they don't need to answer the security question. You can't know in advance who has Autodeposit, so always show the answer.

#### How do I show the security answer to the customer?

The response returns `securityAnswer` encrypted with AES-256-GCM:

```json
"securityAnswer": { "alg": "AES-256-GCM", "iv": "<base64>", "ciphertext": "<base64>", "tag": "<base64>" }
```

Decrypt it on your backend with the security key issued to your account, then show the plain answer to the customer. In sandbox only, the response also includes `plainPassword` with the answer in plain text, so you can check your decryption.

If you send your own `securityQuestion` and `securityAnswer`, send both. The answer needs at least 3 characters and no spaces. If Interac doesn't accept it, the withdrawal is returned as `INCOMPLETE`.

#### How should I build the payout screen?

* Before you create the payout, show the amount and the email address it goes to, and ask the customer to confirm the address. A payout to the wrong address can only be cancelled while it is still `SENT`, through NoLimit support.
* After it is sent, show: "Interac has emailed you at \{email}. Open the email and use this answer: \{answer}." Keep the answer available in the customer's account history.
* Show the payout as pending until you get a final status.
* If it stays `SENT`, remind the customer to look for the Interac email, including in their spam folder.

#### How long does the customer have to accept a payout?

30 days. Until then the withdrawal stays `SENT`. If the customer doesn't accept it, Interac closes it, the withdrawal fails, and the amount is credited back to your balance.

#### Can I pay out straight to a bank account instead of an email?

Yes, with [`POST /withdrawal/account`](/partner-interac-api/send-interac-to-account). Send the customer's institution, transit and account numbers, as well as their name, email address, a memo and the amount.

#### Can I refund a deposit?

Yes, with [`POST /refund`](/partner-interac-api/refund-deposit). It returns all or part of a `COMPLETED` deposit to the customer who paid it, as an Interac e-Transfer. The amount is taken from your balance.

## Statuses and notifications

#### Which statuses should my integration handle?

| Status                                                     | Final? | What to do                                                                      |
| ---------------------------------------------------------- | ------ | ------------------------------------------------------------------------------- |
| `COMPLETED`                                                | Yes    | Success. Credit the customer (deposit) or mark the payout as paid (withdrawal). |
| `REJECTED`, `DECLINED`, `CANCELLED`                        | Yes    | Failed. For a withdrawal, the amount is back in your balance.                   |
| `INCOMPLETE`                                               | Yes    | Failed at creation. No money moved. Create a new transaction if needed.         |
| `PENDING`, `AUTHENTICATED`, `SENT`, `FULFILLED`, `UNKNOWN` | No     | Wait. Show the transaction as pending.                                          |

Read the status from `data.status` in API responses and from the `status` field in webhooks.

#### Should I use webhooks or polling?

Use both. Register a webhook with [`POST /webhooks`](/partner-interac-api/webhook-creation). It is called once, when a deposit, withdrawal or refund reaches a final status.

Webhooks are not retried. If your endpoint is down, or doesn't answer within 10 seconds, that notification is lost. So also poll [`GET /request/{id}`](/partner-interac-api/look-up-deposit-request-by-transaction-id) or [`GET /withdrawal/{id}`](/partner-interac-api/look-up-withdrawal-send-by-transaction-id) for transactions that aren't final, for example every few minutes for the first hour and then a few times a day.

## Testing in sandbox

#### How do I test the full flow in sandbox?

1. **Create a deposit** with `POST /request`. Use a real email address format, and don't use the word "test" in it.
2. **Ask NoLimit support to complete it.** Send the `transactionId` and the status you want (`COMPLETED`, or a failure such as `DECLINED`). Sandbox transactions don't move on their own.
3. **Your sandbox balance now has funds.** New accounts start at zero, so you need a completed deposit before you can test a withdrawal.
4. **Create a withdrawal** with `POST /withdrawal`, and check your decryption against `plainPassword`.
5. **Ask NoLimit support to complete the withdrawal.** Send the `transactionId`, the status you want and the security answer.

In sandbox, you also get a webhook each time a deposit is checked while it is `SENT`. Production sends webhooks only for final statuses.

## How money moves

#### What is the flow of funds?

**Deposit (pay-in):** your customer's bank → Interac → NoLimit → your NoLimit balance.

**Withdrawal (payout):** your NoLimit balance → NoLimit → Interac → your customer's bank.

You never hold or move the money yourself. Your integration creates the request through the API, gives the customer what they need to act on it, and tracks the status. The customer moves the money in their own online banking.

Your NoLimit balance is a ledger:

* A deposit adds its amount when it reaches `COMPLETED`, minus any rolling reserve on your account.
* A withdrawal takes its amount when you create it. If it fails at any point, the amount is credited back.

Check your balance with [`GET /partner/balance`](/partner-interac-api/partner-balance).

#### Who does what?

| Step   | Your integration                                             | Your customer                    | NoLimit and Interac                                |
| ------ | ------------------------------------------------------------ | -------------------------------- | -------------------------------------------------- |
| Create | Calls the API                                                |                                  | Creates the Interac request or payment             |
| Act    | Shows the link (deposit) or the security answer (withdrawal) | Pays or accepts in their banking | Delivers the request or payment                    |
| Settle | Listens for the webhook, or polls                            |                                  | Confirms the final status and updates your balance |

Only the customer, their bank and Interac decide when a transaction is paid, accepted or declined. Neither you nor NoLimit can complete a transaction on the customer's behalf.