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

# Request Interac(deposit)

POST https://sandbox-payments.nolimit.money/interac/request
Content-Type: application/json

Using this API call you can initiate a new Interac transaction. The response will provide you a direct payment link from the Interac system which you will need to handle on your side to get the customer redirected to it for the payment completion.

## Required fields

Every request needs **2 headers** and **4 body fields**, and all of them are required. If any is missing or invalid, the request is refused and no deposit is created.

**Headers (both required)**

* **`x-api-key`**: your credentials, as `<kid>@<api-key>`. If it's missing you get `409` with message `Missing API key`; if it's wrong, `401`.
* **`Idempotency-Key`**: a new UUID v4 for every new deposit. If it's missing you get `400 MISSING_IDEMPOTENCY`; if it's not a UUID v4, `400 INVALID_IDEMPOTENCY_KEY`.

**Body fields (all required)**

* **`amount`** (number): the amount in CAD, for example `25` or `25.50`. Greater than 0, at most `9999`, with at most 2 decimals and no thousands separator. If it's out of range you get `422 INVALID_AMOUNT`; with more than 2 decimals, `422 INVALID_AMOUNT_PRECISION`.
* **`payeeEmail`** (string): the email address of the customer who will pay. It identifies the customer for the one-open-deposit rule and the daily limit. If it isn't a valid email address you get `422 INVALID_EMAIL`.
* **`name`** (string): the customer's full name. If it's missing or empty you get `400 MISSING_NAME`.
* **`memo`** (string): your own description of the transaction, 5 to 200 characters. Only letters, digits, spaces and `. # , $ @ '` are allowed (no `:` or `-`). Otherwise you get `400 MISSING_MEMO`.

Use real email addresses, including when testing in sandbox, and don't use the word "test" anywhere in an email field. Interac can reject the transaction, or ban the email address, when it sees test or made-up addresses. The `example.com` addresses on this page are placeholders only. Thank you for your understanding.

***

The headers must contain a unique `Idempotency-Key` (UUID v4) in order for the API call to be successfull. If reusing an older key the response will include the details of the transaction where the key was first used. It will not create a new transaction.

***

## 409 Conflict

This endpoint returns `409 Conflict` for five different reasons. The HTTP status alone doesn't tell you which one, so always branch on `error.code`.

* **`DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH`**: the customer already has an open deposit for a **different** amount. Send the customer back to the open deposit. See the full explanation below.
* **`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST`**: the `Idempotency-Key` was already used with a different request body. For a new deposit, generate a new key. To replay a request, send exactly the same body: same fields, same values, same field order.
* **`IDEMPOTENCY_IN_PROGRESS`**: a request with this `Idempotency-Key` is still being processed. Wait a few seconds, then retry with the same key and the same body.
* **`BLACKLISTED`**: the `payeeEmail` is blocked. Don't retry. Contact NoLimit support if you think this is a mistake.
* **`BAD_REQUEST`** with message `Missing API key`: the `x-api-key` header was not sent. Send `x-api-key: <kid>@<api-key>`.

### DUPLICATE\_PENDING\_TRANSACTION\_AMOUNT\_MISMATCH

#### The rule

A customer can have only **one open deposit** with you at a time.

* **Customer** means the `payeeEmail`, compared case-insensitively, within your partner account. Deposits created by other NoLimit partners don't count.
* **Open** means the deposit is not final yet: `PENDING`, `AUTHENTICATED`, `SENT`, `FULFILLED` or `UNKNOWN`.
* Deposits that are `COMPLETED`, `REJECTED`, `DECLINED`, `CANCELLED` or `INCOMPLETE` never block a new deposit.
* Only deposits count here. An open withdrawal to the same email doesn't block a deposit. Withdrawals have their own, separate check with the same rules.

#### What happens when the customer already has an open deposit

**Same amount as an open deposit:** no new Interac request is created. You get `201 Created` with the **existing** deposit: its `transactionId`, `status` and `interacLink`.

* The `transactionId` in this response is the original deposit's ID, **not** the `Idempotency-Key` you just sent. Always store the `transactionId` from the response instead of assuming it equals your key.
* Your new `Idempotency-Key` is now linked to that existing deposit. Replaying it returns the same deposit.

**Different amount:** the request is refused with `409 Conflict`:

```json
{
  "success": 0,
  "error": {
    "code": "DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH",
    "message": "These transactions are not finalized: 00000000-0000-4000-8000-000000000001. Either mark them as rejected or completed."
  }
}
```

* `error.message` lists **every** open deposit for this customer, separated by `, `, newest first. This is the only place the blocking IDs are returned.
* "Mark them as rejected or completed" refers to the **customer**: they complete the open deposit by paying it, or reject it by declining it. Neither you nor NoLimit can close a deposit through the API.

#### What the 409 does not mean

* **The open deposit has not failed.** It is still live, and the customer can still pay it. Don't mark it as failed on your side. Customers often pay the original request minutes after a retry was refused.
* **No new deposit was created.** There is no new `transactionId` to track, and no new Interac request was sent to the customer.

#### What happens to your request

* The `Idempotency-Key` you sent is released, not stored. You can send the same key again later with the same body.
* Every retry for a different amount returns the same `409` until **all** the listed deposits are final. Retrying in a loop doesn't help, and repeated refused attempts look like failed payments in your conversion metrics.

#### How the open deposit ends

Only one of these ends it:

1. The customer pays it, through its `interacLink`. It becomes `COMPLETED`.
2. The customer declines it, on the Interac page or in their online banking. It becomes `REJECTED` or `DECLINED`.
3. Nobody acts on it for 30 days, and Interac expires it.

There is no API endpoint to cancel an open deposit.

#### Recommended handling

1. **Branch on the code.** Treat `DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH` as "the customer has an unfinished deposit", not as a failed payment.
2. **Find the open deposit.** Take the transaction ID or IDs from `error.message`, or from your own records for that email. Call `GET /request/{id}` to get its `postedAmount`, `status` and `interacLink`.
3. **Send the customer back to it.** Show the amount and the link, for example: "You have an unfinished deposit of \$50.00. Complete it, or decline it in your online banking, before starting a new one."
4. **Unblock on the final status.** When the webhook or `GET /request/{id}` shows a final status, the customer can start a new deposit for any amount.

#### Avoid the 409 in the first place

* Before calling `POST /request`, check your own records for an open deposit for that email. If there is one, show it to the customer instead of creating a new request.
* If a customer leaves the deposit flow and restarts it for the same amount, reuse the original `Idempotency-Key`. You get the original deposit back.
* Remind customers about unfinished deposits, for example after one hour and again after one day, so open requests are resolved sooner.

#### Order of checks

Checks run in this order. Each one can stop the request before the next:

1. API key (`401`, or `409` when the header is missing)
2. Blacklist (`409 BLACKLISTED`)
3. Body validation, including `DAILY_LIMIT_EXCEEDED` (`400` or `422`)
4. `Idempotency-Key` (`400`, or `409` for the two idempotency codes)
5. Open-deposit check (`201` with the existing deposit, or `409 DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH`)

Reference: https://interacdocs.nolimit.money/partner-interac-api/request-interac-deposit

## Servers

- `https://sandbox-payments.nolimit.money/interac` (Sandbox, default)
- `https://payments.nolimit.money/interac` (Production)

## Request

### Headers

- `x-api-key` (string, required) — Your credentials, as `<kid>@<api-key>`.
- `Idempotency-Key` (string, required) — A new UUID v4 for every new deposit. Reusing a key with the same body returns the original response; with a different body you get `409 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST`.

### Body (application/json)

This endpoint expects an object.

- `amount` (double, required) — Amount in CAD. Greater than 0, at most 9999, with at most 2 decimals.
- `memo` (string, required) — Your own description of the transaction, 5 to 200 characters. Only letters, digits, spaces and `. # , $ @ '` are allowed.
- `payeeEmail` (string, required) — The payer's email address. Use a real email address, even in sandbox, and don't include the word "test". Interac can reject the transaction or ban the address otherwise.
- `name` (string, required) — The customer's full name.

## Response

### 201

Created

- `data` (RequestPostResponsesContentApplicationJsonSchemaData, required)
- `success` (integer, required)

## Errors

### 400 Bad Request Error

Bad Request

- `success` (integer, required)
- `error` (RequestPostResponsesContentApplicationJsonSchemaError, required)

### 409 Conflict Error

Conflict. Check `error.code`; see the 409 Conflict section above.

- `success` (integer, required) — Always 0 for errors.
- `error` (RequestPostResponsesContentApplicationJsonSchemaError, required)

## Types

### RequestPostResponsesContentApplicationJsonSchemaData

- `transactionId` (string, required)
- `referenceNumber` (string, required)
- `status` (string, required)
- `payeeEmail` (string, required)
- `recipientEmail` (string, required)
- `interacLink` (string, required)
- `postedAmount` (integer, required)

### RequestPostResponsesContentApplicationJsonSchemaError

- `code` (string, required) — Machine-readable reason. Branch on this value.
- `message` (string, optional) — Human-readable detail. For DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH, lists the open deposit IDs.

## Examples

**Request**

```json
{
  "amount": 1,
  "memo": "ACME INC Payment for Order HJ68GY75",
  "payeeEmail": "john.doe@example.com",
  "name": "John Doe"
}
```

**Response**

```json
{
  "data": {
    "transactionId": "2ffb7139-0b50-4840-998b-3cafbe80ebfa",
    "referenceNumber": "CA1MRrjEyVQu",
    "status": "PENDING",
    "payeeEmail": "john.doe@example.com",
    "recipientEmail": "payments@example.com",
    "interacLink": "https://gateway-web.fit.interac.ca/acceptPaymentRequest.do?rID=CA1MRrjEyVQu",
    "postedAmount": 20
  },
  "success": 1
}
```

**SDK Code**

```python Request Interac(deposit)_example
import requests

url = "https://sandbox-payments.nolimit.money/interac/request"

payload = {
    "amount": 1,
    "memo": "ACME INC Payment for Order HJ68GY75",
    "payeeEmail": "john.doe@example.com",
    "name": "John Doe"
}
headers = {
    "Idempotency-Key": "6f1c2b8e-4a7d-4c3e-9b2f-8d5a1e7c0f42",
    "x-api-key": "<kid>@<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Request Interac(deposit)_example
const url = 'https://sandbox-payments.nolimit.money/interac/request';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '6f1c2b8e-4a7d-4c3e-9b2f-8d5a1e7c0f42',
    'x-api-key': '<kid>@<api-key>',
    'Content-Type': 'application/json'
  },
  body: '{"amount":1,"memo":"ACME INC Payment for Order HJ68GY75","payeeEmail":"john.doe@example.com","name":"John Doe"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request Interac(deposit)_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-payments.nolimit.money/interac/request"

	payload := strings.NewReader("{\n  \"amount\": 1,\n  \"memo\": \"ACME INC Payment for Order HJ68GY75\",\n  \"payeeEmail\": \"john.doe@example.com\",\n  \"name\": \"John Doe\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "6f1c2b8e-4a7d-4c3e-9b2f-8d5a1e7c0f42")
	req.Header.Add("x-api-key", "<kid>@<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request Interac(deposit)_example
require 'uri'
require 'net/http'

url = URI("https://sandbox-payments.nolimit.money/interac/request")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '6f1c2b8e-4a7d-4c3e-9b2f-8d5a1e7c0f42'
request["x-api-key"] = '<kid>@<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 1,\n  \"memo\": \"ACME INC Payment for Order HJ68GY75\",\n  \"payeeEmail\": \"john.doe@example.com\",\n  \"name\": \"John Doe\"\n}"

response = http.request(request)
puts response.read_body
```

```java Request Interac(deposit)_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://sandbox-payments.nolimit.money/interac/request")
  .header("Idempotency-Key", "6f1c2b8e-4a7d-4c3e-9b2f-8d5a1e7c0f42")
  .header("x-api-key", "<kid>@<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1,\n  \"memo\": \"ACME INC Payment for Order HJ68GY75\",\n  \"payeeEmail\": \"john.doe@example.com\",\n  \"name\": \"John Doe\"\n}")
  .asString();
```

```php Request Interac(deposit)_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://sandbox-payments.nolimit.money/interac/request', [
  'body' => '{
  "amount": 1,
  "memo": "ACME INC Payment for Order HJ68GY75",
  "payeeEmail": "john.doe@example.com",
  "name": "John Doe"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '6f1c2b8e-4a7d-4c3e-9b2f-8d5a1e7c0f42',
    'x-api-key' => '<kid>@<api-key>',
  ],
]);

echo $response->getBody();
```

```csharp Request Interac(deposit)_example
using RestSharp;

var client = new RestClient("https://sandbox-payments.nolimit.money/interac/request");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "6f1c2b8e-4a7d-4c3e-9b2f-8d5a1e7c0f42");
request.AddHeader("x-api-key", "<kid>@<api-key>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"amount\": 1,\n  \"memo\": \"ACME INC Payment for Order HJ68GY75\",\n  \"payeeEmail\": \"john.doe@example.com\",\n  \"name\": \"John Doe\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Request Interac(deposit)_example
import Foundation

let headers = [
  "Idempotency-Key": "6f1c2b8e-4a7d-4c3e-9b2f-8d5a1e7c0f42",
  "x-api-key": "<kid>@<api-key>",
  "Content-Type": "application/json"
]
let parameters = [
  "amount": 1,
  "memo": "ACME INC Payment for Order HJ68GY75",
  "payeeEmail": "john.doe@example.com",
  "name": "John Doe"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-payments.nolimit.money/interac/request")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```