Skip to navigation

Send Interac to Account

View as Markdown

Using this API call you can initiate a new Interac withdrawal (Send) directly to a bank account number. The response will provide the details of the send along with a password which can be used to accept the transaction.

Be sure to provide the information needed in the body of the API call:

  • firstName - [string:no limit] the payee’s First Name

  • lastName - [string:no limit] the payee’s Last Name

  • payoutEmail - [email:no limit] the receiver’s valid email address

  • memo - [string:5-200] Allowed Symbols: (.#,$@') Minimum 5 characters - treat this as your own custom transaction description. It is surfaced on the Interac payment page at the moment the customer is making the payment.

  • amount - [float]positive values. Can include 2 decimal numbers. No delimiter. Decimal should be . (dot). Cannot be more than the current available account balance.

  • accountNumber- [string:no limit]- Generally composed out of 5-12 digits

  • institutionNumber- [string:no limit]- Generally composed out of 3 digits. Has to be a valid institution number

  • transitNumber- [string:no limit]- Generally composed out of 5 digits. Has to be a valid transitNumber for the above institution

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 four 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 withdrawal for a different amount. See the full explanation below.
  • 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 payoutEmail or the bank account (institutionNumber, transitNumber, accountNumber) 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>.

Withdrawals have no check for a reused Idempotency-Key with a different body. If you send a key that was already used, you get the original response back, even if the body is different, and no new withdrawal is created. Always generate a new key for a new withdrawal.

DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH

The rule

A customer can have only one open withdrawal from you at a time.

  • Customer means the payoutEmail, compared case-insensitively, within your partner account. Withdrawals created by other NoLimit partners don’t count.
  • One check covers both withdrawal endpoints. An open withdrawal sent with POST /withdrawal (by email) blocks a new POST /withdrawal/account (to a bank account) for the same payoutEmail, and the other way round.
  • Open means the withdrawal is not final yet: PENDING, AUTHENTICATED, SENT, FULFILLED or UNKNOWN.
  • Withdrawals that are COMPLETED, REJECTED, DECLINED, CANCELLED or INCOMPLETE never block a new withdrawal.
  • Only withdrawals count here. An open deposit from the same email doesn’t block a withdrawal. Deposits have their own, separate check with the same rules (see POST /request).

What happens when the customer already has an open withdrawal

Same amount as an open withdrawal: no new withdrawal is created and your balance is not debited again. You get 201 Created with the existing withdrawal.

  • The transactionId in this response is the original withdrawal’s ID, not the Idempotency-Key you just sent. Always store the transactionId from the response instead of assuming it equals your key.
  • The response carries the existing withdrawal’s securityQuestion and securityAnswer. Any security question and answer you sent in the new request are ignored. Give the customer the answer from this response. For a bank-account withdrawal, the money goes to the bank account of the existing withdrawal, not to the account in your new request.
  • Your new Idempotency-Key is now linked to that existing withdrawal. Replaying it returns the same withdrawal.

Different amount: the request is refused with 409 Conflict:

{
"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 withdrawal 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 withdrawal by accepting the money, or reject it by declining it. You can’t close a withdrawal through the API.

What the 409 does not mean

  • The open withdrawal has not failed. It is still live, and the customer can still accept it. Don’t mark it as failed on your side.
  • No new withdrawal was created, and your balance was not debited. There is no new transactionId to track.

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 withdrawals are final.

How the open withdrawal ends

Only one of these ends it:

  1. The customer accepts the money from the Interac email. It becomes COMPLETED.
  2. The customer declines it, or their bank does. It becomes DECLINED or REJECTED.
  3. Nobody acts on it for 30 days, and Interac expires it.
  4. It was sent to the wrong email address and you ask NoLimit support to cancel it. This is possible only while it is still SENT, and it becomes CANCELLED.

There is no API endpoint to cancel an open withdrawal.

  1. Branch on the code. Treat DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH as “the customer has an unaccepted payout”, not as a failed payout.
  2. Find the open withdrawal. Take the transaction ID or IDs from error.message, or from your own records for that email. Call GET /withdrawal/{id} to get its postedAmount and status.
  3. Tell the customer. For example: “You have a payout of $50.00 waiting. Accept it from the Interac email before requesting another one.”
  4. Unblock on the final status. When the webhook or GET /withdrawal/{id} shows a final status, you can send the customer a new withdrawal for any amount.

Avoid the 409 in the first place

  • Before sending a withdrawal, check your own records for an open withdrawal to that email.
  • If you need to pay the customer more while a payout is still open, wait until the customer accepts it, then send the difference as a new withdrawal.
  • Remind customers to accept their payouts, so open withdrawals 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 IDEMPOTENCY_IN_PROGRESS)
  5. Withdrawals availability (403 WITHDRAWAL_UNAVAILABLE)
  6. Open-withdrawal check (201 with the existing withdrawal, or 409 DUPLICATE_PENDING_TRANSACTION_AMOUNT_MISMATCH)
  7. Balance (400 INSUFFICIENT_FUNDS)

Headers

x-api-keystringOptional
Idempotency-KeystringOptional

Request

This endpoint expects an object.
firstNamestringRequired
lastNamestringRequired
payoutEmailstringRequiredformat: "email"
The receiver'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.
memostringRequired
amountintegerRequired
accountNumberstringRequired
institutionNumberstringRequired
transitNumberstringRequired

Response headers

access-control-allow-originstringOptional
referrer-policystringOptional
x-xss-protectionstringOptional
origin-agent-clusterstringOptional
x-dns-prefetch-controlstringOptional
x-permitted-cross-domain-policiesstringOptional
etagstringOptional
cross-origin-opener-policystringOptional
cross-origin-resource-policystringOptional
x-download-optionsstringOptional
x-frame-optionsstringOptional
strict-transport-securitystringOptional
x-content-type-optionsstringOptional
content-security-policystringOptional
access-control-allow-credentialsstringOptional
apigw-requestidstringOptional
cf-cache-statusstringOptional
NelstringOptional
Report-TostringOptional
CF-RAYstringOptional

Response

Created
dataobject
successinteger

Errors

409
Conflict Error