- METHOD TYPEReal-Time Bank Transfer
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
Introduction
Interac eCashout, a product of Express Connect E-wallet, is a popular alternative payment method in Canada for both businesses and individuals. It allows users to fund their E-wallets and make online payments without having to enter card details every time. It is a flexible and convenient payment processing feature.
Interac eCashout allows your customers to link any number of their Canadian bank accounts to their email address. The Nuvei platform encrypts your customer’s bank account details securely, and provides a userPaymentOptionId
(UPO) representing the account for you to use in transactions.
Prerequisites and Notes
- This guide assumes you have completed all account setup prerequisites, and are ready to integrate Interac eCashout into your payment flow.
- Interac eCashout only supports Canadian based IPs.
- Payout (withdrawal) transactions are conducted in Canadian Dollars between Canadian bank accounts.
- Nuvei handles Interac eCashout transactions in “redirection mode”.
- A UPO (user payment option) is an encrypted customer payment method record stored in the Nuvei system, representing a customer bank account or other payment method.
- Test credentials and testing scenarios can be provided by Nuvei if necessary. You can contact Nuvei support for assistance.
Supported Countries
- Canada
Supported Currencies
- CAD
Payout (Withdrawal) Flow
The following two methods can be used to process a /payout
request with Interac eCashout:
- By collecting the customer’s bank account details using the
/accountCapture
method. - By creating a UPO, which represents the customer’s bank account details, with the
/addUPOAPM
method
Press tab to open…
- Generate a
sessionToken
. Press here for details. - Send an
/accountCapture
request that includes the following mandatory fields as shown in the example request below:userTokenId
– Unique customer identifier in merchant system.paymentMethod
: “apmgw_Express_Connect“currencyCode
: CADcountryCode
: CA
Example
/accountCapture
Request{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "paymentMethod": "apmgw_Express_Connect", "currencyCode": "CAD", "countryCode": "CA", }
The request returns a
redirectUrl
.Example
/accountCapture
Response{ "reason": "", "redirectUrl": "https://interac.express-connect.com/webflow/verify?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhbW91bnQiOiIxIiwiYWRkcmVzcyI6IjI5OTIgQ2FtZXJvbiBSb2FkIiwiY2l0eSI6Ik5ld2FyayIsInNhbmRib3giOiJ0cnVlIiwibW9iaWxlIjoiMDg4ODg4ODQzMiIsImxhc3RfbmFtZSI6IkJPQkJFVEhDSEFSTEVTT04iLCJ0eXBlIjoiS1k0IiwidXNlcklkIjoiQ0Q1MDFBRjlGQTg1MDAxN0M5Mzk5QjZGNTlGRDNDMTUiLCJzaXRlIjoidGVzdCIsInByb3ZpbmNlIjoiTlkiLCJET0IiOiIxOTk3LTA5LTI2IiwidXNlcklwIjoiMTE0LjEzLjEyLjExIiwiY3VycmVuY3kiOiJDQUQiLCJwb3N0YWxfY29kZSI6IjE0MjM2IiwibGFuZyI6ImVuIiwiZmlyc3RfbmFtZSI6IkFMQkVSVEEiLCJlbWFpbCI6ImFjY291bnR0ZXN0bWFpbEBnbS5jb20iLCJ0cmFuc2FjdGlvbiI6IkNENTAxQUY5RkE4NTAwMTdDOTM5OUI2RjU5RkQzQzE1IiwidXNlciI6ImJmMGRhODViZjgyOTMyZWVmMjFhY2ZhNzM0YjZmNjA1IiwiY2FtcGFpZ24iOiI2YWMwZmYzYzY5NTdiNmY4ZTVkMDgxM2Y1MjY4OWNlMyIsImVudGl0eUlkIjoxLCJpYXQiOjE3MDE3OTIyMjAsImV4cCI6MTcwMTg3ODYyMH0.YeG1n2gTpA37JLDZSntpbnhTZkb2lLMDendqihF3Lx4", "merchantId": "2502136204546424962", "errCode": 0, "sessionToken": "aff5c587-6d76-42f5-bcbe-934209753951", "internalRequestId": 35455681, "userTokenId": "42WPMSNLOBAT", "version": "1.0", "status": "SUCCESS", "merchantSiteId": "126006" }
- Use
redirectUrl
to redirect the customer to the APM’s account details capture interface for them to enter their account details. - Once the information is captured, Nuvei stores the data in a
userPaymentOptionId
identifier, and sends a Direct Merchant Notification (DMN) back to you with the newly createduserPaymentOptionId
. - Send a /payout request and include the
userPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example.
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided inurlDetails.notificationUrl
, which Nuvei recommends including in the/payout
request.
1. Register a userTokenId
A userTokenId
is a field in the Nuvei system containing the user’s identifier in the merchant system.
If you do not have a userTokenId
registered in the Nuvei system for this user, then register one by sending a /createUser
request, including email
, countryCode
, firstName
, and lastName
.
Example /createUser
Request
{ "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "currency": "CAD", "amount": "100", "userPaymentOption": { "userPaymentOptionId": "<ID of a previously stored payment option>" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example /createUser
Response
{ "transactionStatus": "APPROVED", "clientRequestId": "W1Q3SBGE4", "internalRequestId": 17817071, "version": "1.0", "transactionId": "2110000000004333013", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "userPaymentOptionId": "8054521", "paymentMethodErrorCode": 0, "userTokenId": "CEBQK9OVSLJA", "externalTransactionId": "2110000000068709", "status": "SUCCESS" }
2. Create the UPO
Create a UPO by sending an /addUPOAPM
request and include:
userTokenId
– The unique user identifier in your system.paymentMethodName
: “apmgw_Express_Connect“apmData
block containing:accountNumber
– User account numberinstitutionNumber
– User institution numbertransitNumber
– User account transmit number
billingAddress
block containing:country
andemail
Example /addUPOAPM
Request
{ "merchantSiteId":"<your merchantSiteId>", "merchantId":"<your merchantId>", "userTokenId":"<unique customer identifier in merchant system>", "clientRequestId":"<unique request ID in merchant system>", "paymentMethodName":"apmgw_Express_Connect", "apmData":{ "accountNumber":"<1234567>", "institutionNumber": "<123>", "transitNumber": "<12345>" }, "billingAddress":{ "country":"CA", "email":"[email protected]" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
Example /addUPOAPM
Response
{ "userPaymentOptionId":2152829771, "internalRequestId":25129841, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"1102398682906145682", "merchantSiteId":"228311", "version":"1.0", "clientRequestId":"20230228133537" }
3. Send a /payout
Request
Send a /payout
request and include the userPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example.
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in urlDetails.notificationUrl
, which Nuvei recommends including in the /payout
request.
-
/accountCapture
-
- Generate a
sessionToken
. Press here for details. - Send an
/accountCapture
request that includes the following mandatory fields as shown in the example request below:userTokenId
– Unique customer identifier in merchant system.paymentMethod
: “apmgw_Express_Connect“currencyCode
: CADcountryCode
: CA
Example
/accountCapture
Request{ "sessionToken": "<sessionToken from /getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "paymentMethod": "apmgw_Express_Connect", "currencyCode": "CAD", "countryCode": "CA", }
The request returns a
redirectUrl
.Example
/accountCapture
Response{ "reason": "", "redirectUrl": "https://interac.express-connect.com/webflow/verify?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhbW91bnQiOiIxIiwiYWRkcmVzcyI6IjI5OTIgQ2FtZXJvbiBSb2FkIiwiY2l0eSI6Ik5ld2FyayIsInNhbmRib3giOiJ0cnVlIiwibW9iaWxlIjoiMDg4ODg4ODQzMiIsImxhc3RfbmFtZSI6IkJPQkJFVEhDSEFSTEVTT04iLCJ0eXBlIjoiS1k0IiwidXNlcklkIjoiQ0Q1MDFBRjlGQTg1MDAxN0M5Mzk5QjZGNTlGRDNDMTUiLCJzaXRlIjoidGVzdCIsInByb3ZpbmNlIjoiTlkiLCJET0IiOiIxOTk3LTA5LTI2IiwidXNlcklwIjoiMTE0LjEzLjEyLjExIiwiY3VycmVuY3kiOiJDQUQiLCJwb3N0YWxfY29kZSI6IjE0MjM2IiwibGFuZyI6ImVuIiwiZmlyc3RfbmFtZSI6IkFMQkVSVEEiLCJlbWFpbCI6ImFjY291bnR0ZXN0bWFpbEBnbS5jb20iLCJ0cmFuc2FjdGlvbiI6IkNENTAxQUY5RkE4NTAwMTdDOTM5OUI2RjU5RkQzQzE1IiwidXNlciI6ImJmMGRhODViZjgyOTMyZWVmMjFhY2ZhNzM0YjZmNjA1IiwiY2FtcGFpZ24iOiI2YWMwZmYzYzY5NTdiNmY4ZTVkMDgxM2Y1MjY4OWNlMyIsImVudGl0eUlkIjoxLCJpYXQiOjE3MDE3OTIyMjAsImV4cCI6MTcwMTg3ODYyMH0.YeG1n2gTpA37JLDZSntpbnhTZkb2lLMDendqihF3Lx4", "merchantId": "2502136204546424962", "errCode": 0, "sessionToken": "aff5c587-6d76-42f5-bcbe-934209753951", "internalRequestId": 35455681, "userTokenId": "42WPMSNLOBAT", "version": "1.0", "status": "SUCCESS", "merchantSiteId": "126006" }
- Use
redirectUrl
to redirect the customer to the APM’s account details capture interface for them to enter their account details. - Once the information is captured, Nuvei stores the data in a
userPaymentOptionId
identifier, and sends a Direct Merchant Notification (DMN) back to you with the newly createduserPaymentOptionId
. - Send a /payout request and include the
userPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example.
After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided inurlDetails.notificationUrl
, which Nuvei recommends including in the/payout
request.
- Generate a
-
/addUPOAPM
-
1. Register a
userTokenId
A
userTokenId
is a field in the Nuvei system containing the user’s identifier in the merchant system.If you do not have a
userTokenId
registered in the Nuvei system for this user, then register one by sending a/createUser
request, includingemail
,countryCode
,firstName
, andlastName
.Example
/createUser
Request{ "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "currency": "CAD", "amount": "100", "userPaymentOption": { "userPaymentOptionId": "<ID of a previously stored payment option>" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example
/createUser
Response{ "transactionStatus": "APPROVED", "clientRequestId": "W1Q3SBGE4", "internalRequestId": 17817071, "version": "1.0", "transactionId": "2110000000004333013", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "userPaymentOptionId": "8054521", "paymentMethodErrorCode": 0, "userTokenId": "CEBQK9OVSLJA", "externalTransactionId": "2110000000068709", "status": "SUCCESS" }
2. Create the UPO
Create a UPO by sending an
/addUPOAPM
request and include:userTokenId
– The unique user identifier in your system.paymentMethodName
: “apmgw_Express_Connect“apmData
block containing:accountNumber
– User account numberinstitutionNumber
– User institution numbertransitNumber
– User account transmit number
billingAddress
block containing:country
andemail
Example
/addUPOAPM
Request{ "merchantSiteId":"<your merchantSiteId>", "merchantId":"<your merchantId>", "userTokenId":"<unique customer identifier in merchant system>", "clientRequestId":"<unique request ID in merchant system>", "paymentMethodName":"apmgw_Express_Connect", "apmData":{ "accountNumber":"<1234567>", "institutionNumber": "<123>", "transitNumber": "<12345>" }, "billingAddress":{ "country":"CA", "email":"[email protected]" }, "timeStamp":"<YYYYMMDDHHmmss>", "checksum":"<calculated checksum>" }
Example
/addUPOAPM
Response{ "userPaymentOptionId":2152829771, "internalRequestId":25129841, "status":"SUCCESS", "errCode":0, "reason":"", "merchantId":"1102398682906145682", "merchantSiteId":"228311", "version":"1.0", "clientRequestId":"20230228133537" }
3. Send a
/payout
RequestSend a
/payout
request and include theuserPaymentOptionId
, which contains the user’s previously stored APM account details. Press here for an example.After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to the URL provided in
urlDetails.notificationUrl
, which Nuvei recommends including in the/payout
request.
User Experience
- The user is redirected to third-party page to log in to their bank and confirm the request.
A withdrawal request is created. - The merchant processes the withdrawal via API or from the back office Control Panel.
The merchant is able to see the bank capture transaction on the Control Panel, as well as the details that were provided by the bank. The merchant can then decide whether to process the payout or not.
Testing
User details for the KYC flow:
first_name | John |
last_name | Smith |
address | 4101 Yonge Suite 501 |
city | Toronto |
province | ON |
country | CA |
postal_code | M2P 1N6 |
DOB | 1990-01-26 00:00:00 |
[email protected] | |
mobile | 14164541210 |