- METHOD TYPEReal-Time Bank Transfer; Bank Transfer
- PAYMENT
- PAYOUT
- REFUNDS
Introduction
The Nuvei Interac Instant integration allows your customers to pay you from their selected bank accounts, and allows you to make payouts to them, using these Interac Instant methods:
- Interac Online – Provides online payment services in near-realtime.
- Interac e-Transfer – Provides an “open loop” offline payment services, where the customer submits a payment request and then copies the unique payment details into their bank account website or app to complete the payment flow.
This guide describes the steps to integrate Interac Instant as a Nuvei APM (alternative payment method) into your payment flows, enabling customer payments, and allowing you to perform payouts, using Nuvei’s server-to-server REST API calls.
Interac Instant 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 set up prerequisites, and are ready to integrate the Interac Instant APM payment method into your payment flow.
- Interac Instant only supports Canadian based IPs.
- Payments (“deposits”) and payout (“withdrawal”) transactions are conducted in Canadian Dollars between Canadian bank accounts.
- Nuvei handles Interac Instant transactions in “redirection mode”.
- The system sends DMNs (direct merchant notifications) to ensure that you receive the results of transaction processing. You need to include a destination DMN
notificationUrl
in all/payment
and/payout
requests. You can either set the notification URL hard coded on the CPanel, or send it in each request. - 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
Interac Instant Payments
- The payment flow begins on your payment page when your customer enters an
amount
they wish to pay you, and selects the Interac Instant APM payment method. - Generate a
sessionToken
by sending a/getSessionToken
request. - Call a
/payment
request with its mandatory parameters and include the following:paymentOption.alternativePaymentMethod.paymentMethod: "apmgw_INTERAC_Instant"
- Note: Canadian
phone
numbers must be 10 digits, without the country code.
Example
/payment
Request{ "sessionToken": "<sessionToken from getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "userTokenId": "<unique customer identifier in merchant system>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "currency": "CAD", "amount": "100", "paymentOption": { "alternativePaymentMethod": { "paymentMethod": "apmgw_INTERAC_Instant" } }, "userDetails": { "firstName": "john", "lastName": "smith", "country": "CA" }, "deviceDetails": { "ipAddress": "127.0.0.1" }, "billingAddress": { "email": "john.smith@email.com", "country": "CA" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example
/payment
Response{ "reason": "", "orderId": "36298881", "transactionStatus": "REDIRECT", "clientRequestId": "GF1XTXTBM", "internalRequestId": 17817111, "version": "1.0", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiNzRDQkZEODMyOUI1RDMwMjNDM0YwNUJERThGRkFEMDRGQUNEMURCQUZFMEYxM0QwMzhFQkU5RjRCMzhFMTY2RTY5NEI0QzhDMDg2RjYzMDM2RTdCMkIyREVBRjRENTIyNkM2RDg1RUE5NkI2QjIzNjEzMUVBREI0NDBGRjU0QzE0RThGM0ZCODg2QzUwQzcyMTYxMURBMkNBQzg1NzI2NjRCOEE4ODE0MThEMkJCMjBFNTAzRDE4MTRBMkJBM0M1NjM3RDBCNkFFRDU5MUVFQzk2NEQwMUE2OEFFRUQyMDBBMUJBRUQ4RUIxNDBGNEEwQkQ2OTE3MzYxMEM4Rjg1MTAwMjMxREEzQkRDNUZGMkNGOUNGRURCQkZFMTQ2REEwMDdCQUY4QUUzN0Q1Q0JEQTYzOTQyNDhGMkFEQzhFMzMyODU4NzQ5MzUyNTI2NDFFREREM0Q4ODEwQTE3RkVCNTlBMjY4ODBCMkI2NjYzRkVENjk3RjRBMDhERTFBNzVDRDdBMzk2MzBGRjJBREU1Mjk0N0FERjFFQUVFMDA4Nzg4Q0REN0RCNjM5M0QwRTNEOTFBQkVERTY3MDFBMUQ0RkU3M0M3RTQwNUQ5RjlCNzZDMUYxRjQ5QzIxMjU4RERENDVDQUFDNTNERDg4MEVBNTk2Mzk1QzBDRDQ4NUY0OTQ4M0VERURGNDJFRkQzMUJBNkIwMUYwMTFGMTVGNzAyMUI2OTRBOUQ1NTU0OEEyQ0FDNUQ3MzVBNTgyMkJCMEFDOUFCQjhBQzc1Q0UxNzc1NjI0QzY1QUQ1MDU4NTVCRDI5RjFCMjJCMDlCREExM0I1QkFFQ0ZEMTA1MUI2NTQ4QTUxQkJDNDlEOTlCQUI4MUZERjAwNzAyQTBDQ0IyQTk3MDVENzE2MkZFRUQ5RjEzN0ZGN0FGMDUwNUIyMUIwOTY2RDA2NTFFQkRDRDA1MkY0RTE4MDY5ODlCOEFBQjJDMTIxNkIzNzJDREQ5RDQ0RDQ2N0EwOEUwQjI4MkUzOTkwNjAwOTcyQ0NDNEYwQjZEMDdERDg1ODk2MDYzM0UwNkExQ0VGRTY0OEExNzBDOTA3RjA3Qzg4NDA4NDI0MzQzRjNGQjM1MDZFN0EzRkEwNkQ0MDY5M0QyQkE3MzBGQTdCNzc3NDFFQUU2NDg2NEI2NjE3MDdGMzY0MDNCMTQyOTJDMTM1NzI5NDUwQ0YxRDk3NTcxQUE5NzJDQzg1MTVGQSIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6Ijk5RTM0MEMyNzg0MkNBOTlCQkIxQzUyNzVFQUFFNURBIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.EF3K5UsPQYdua_YcRd9Yefl-KemNwEMq5-EXV7QWAZUbCQglncAaAHzzlW-sxq2XcVZcZ2qbxLkQqjzkB3tItTGUDmqysL-opqOdaaz54EKeHKC5hzQIp77DucIGYQhPxfOB_eAxTOPLvZ85c3woJ37m8BH8kuJPSoAjYrZ12geEQJQx4R2VxNT3QsxxryEWZvU1yKc8mjCl011nWz6cp4LZpHIMwUwvdCMJWUeJtAxC-Q6Ec4NqP93AFki9Ln0OOvenbOEBn3UpK_BncxKu7RFOzM8w4kSf0eopKC44awlROwZaO0k0htJAUikA_W-fgeLISuMpHmWMZz6X3Ju2Bg", "userPaymentOptionId": "8061731", "card": {} }, "sessionToken": "6fa38ea2-6f1a-4620-85ae-7deaf0d5f8f1", "userTokenId": "2J6QZH3UF9E2", "status": "SUCCESS" }
A successful request returns a
redirectUrl
(to an Interac Instant URL).
- Redirect the customer to the
redirectUrl
address, so they can choose the bank that holds their account from which they wish to pay.
Example Interac Instant Bank Selection Page
- After choosing the bank (in our example: “BMO Bank”), the customer selects their preferred Interac Instant transfer method:
- Interac Online – This is a realtime option where the customer logs directly in to their bank site, selects the account from which they wish to pay and authorizes the payment in near-realtime.
- Interac e-Transfer – This is an “open loop” flow, where the system displays the payment details and
APMReferenceID
, as well as instructions for the customer to complete the transaction on their bank account website or app.
Example Interac Instant Method Selection Page
For Interac Online
- The customer logs directly in to their bank site or app, and selects the bank account from which they wish to pay and authorizes the payment.
- Interac Instant processes the request in near-realtime.
- When processing is complete, you receive a DMN notification in near-realtime, with a
status
of either:Status=APPROVED
Status=DECLINED
– The process ends here!
For Interac e-Transfer
- The system displays the payment details and
APMReferenceID
, as well as instructions for the customer to complete the transaction.
Example Interac e-Transfer Transfer
- The customer follows the instructions, for example:
- To log in to their bank account website or app, and copy the unique payment details displayed, into their bank page.
- To complete the payment, the customer may need to present the
APMReferenceID
at a bank, ATM, or on an online banking site, and pay the money.
- When processing is complete, you receive a DMN notification in near-realtime (sent to the
urlDetails.notificationUrl
parameter that you provided in the request), with astatus
of either:APPROVED
– You receive a DMN with “status=APPROVED
“.DECLINED
– You receive a DMN with “status=DECLINED
“.
The process ends here!
- If the payment is successful, then the Nuvei system generates and return the following identifiers that you can store in your system for future use, when sending an Interac Instant Payout (which requires a UPO):
userTokenId
– Representing the customeruserPaymentOptionId
(UPO) – Representing the customer’s bank account.
Interac Instant Payouts
Interac Instant allows you to pay money to your customers using the /payout
REST API method.
A /payout
request requires a userPaymentOptionId
(UPO) parameter, which represents the customer’s bank account.
Interac Instant requires that the UPO record should contain these security question parameters:
interac_instant_security_question
interac_instant_security_answer
Interac Instant Payout Flow
- The Interac Instant Payout flow begins when you want to pay money into the customer’s bank account.
- Retrieve the customer’s
userTokenId
:- If your customer does not yet have a
userTokenId
, then generate one by sending a customer identifier, from your system, in a/createUser
request. - If this is a returning-customer, then retrieve the customer’s
userTokenId
stored in your system.
- If your customer does not yet have a
- Send the customer’s
userTokenId
in a/getUserUPOs
request to retrieve a list of their UPOs (and their security questions). - Display these UPOs for the customer to choose from (also display the option to choose another account).
- Handle the customer’s selection:
- If the customer selects one of their previously stored UPOs for you to pay the money into, then:
- Check the output from the
/getUserUPOs
request to see if the selected UPO contains the security question parameters, located at:paymentMethods.upoData.interac_instant_security_question
paymentMethods.upoData.interac_instant_security_answer
- If the selected UPO does not have a security question, then add a UPO security question.
- Check the output from the
- If the customer decides not to use one of their existing UPOs, but instead provides other bank details, then use these to generate a UPO.
- If the customer selects one of their previously stored UPOs for you to pay the money into, then:
- Now that you have a UPO that contains a security question, use the relevant
userTokenId
anduserPaymentOptionId
to send a/payout
request.
Example
/payout
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": "35", "userPaymentOption": { "userPaymentOptionId": "<UPO received from previous deposit>" }, "deviceDetails": { "ipAddress": "127.0.0.1" }, "urlDetails": { "notificationUrl": "[The URL to which DMNs are sent]" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example
/payout
Response{ "reason": "", "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" }
- After the transaction is processed, you receive a DMN notification (sent to the
urlDetails.notificationUrl
parameter that you provided in the request), that includes the result of the transaction, for example:Status=PENDING
andStatus=APPROVED
.
Testing
Data | Value |
---|---|
First Name | Larry |
Last Name | Johnson |
Email Address | Any valid email address Example: person@test.com |
Phone Number | Any 10-digit number Example: 0745123456 |
Appendix
Generating a UPO
Follow these steps to generate a UPO for the selected customer bank account, for use in Interac Instant transactions:
- If your customer does not yet have a
userTokenId
, then generate one by sending a customer identifier, from your system, in a/createUser
request. - Send the customer’s
userTokenId
in an/addUPOAPM
request, and include the following additional Interac Instant parameters in anapmData
block:interac_instant_email
interac_instant_phone
(Canadianphone
numbers must be 10 digits, without the country code.)interac_instant_security_question
interac_instant_security_answer
(6–25 characters, no spaces, no special characters)
Example /addUPOAPM
Request
{ "merchantId": "2502136204546424962", "merchantSiteId": "<your merchantId>", "clientRequestId": "<unique request ID in merchant system>", "userTokenId": "<unique customer identifier in merchant system>", "paymentMethodName":"apmgw_INTERAC_Instant", "apmData":{ "interac_instant_email": "accountholder0@example.com", "interac_instant_phone": "1112223333", "interac_instant_security_question": "<some security question>", "interac_instant_security_answer": "<6 - 25 characters no spaces no special characters>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example /addUPOAPM
Response
{ "reason": "", "merchantId": "2502136204546424962", "errCode": 0, "clientRequestId": "HWMTWQ2RT", "userPaymentOptionId": 8052151, "internalRequestId": 17817221, "version": "1.0", "status": "SUCCESS", "merchantSiteId": "126006" }
Add UPO Security Questions
Interac Instant requires that the UPO record (representing the customer’s bank account) used in a /payout
request should contain these security question parameters: interac_instant_security_question
and interac_instant_security_answer
.
Send the customer’s userTokenId
, that is stored in your system, in an /editUPOAPM
request and include the following additional Interac Instant parameters in the apmData
block:
interac_instant_email
interac_instant_phone
(Canadianphone
numbers must be 10 digits, without the country code.)interac_instant_security_question
interac_instant_security_answer
(6–25 characters, no spaces, no special characters)
Example /editUPOAPM
Request
{ "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantId>", "clientRequestId": "<unique request ID in merchant system>", "userTokenId": "<unique customer identifier in merchant system>", "userPaymentOptionId": "<UPO received from previous deposit>", "apmData":{ "interac_instant_email": "accountholder0@example.com", "interac_instant_phone": "1112223333", "interac_instant_security_question": "<some security question>", "interac_instant_security_answer": "<6 - 25 characters no spaces no special characters>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example /editUPOAPM
Response
{ "reason": "", "merchantId": "2502136204546424962", "errCode": 0, "clientRequestId": "HWMTWQ2RT", "internalRequestId": 17817221, "version": "1.0", "status": "SUCCESS", "merchantSiteId": "126006" }
——————–
The following material was not used because the functionality does not exist yet.
I kept if in case we do provide this functionality later:
- For a returning-customer:
- Retrieve the customer’s
userTokenId
that is stored in your system, and send it in a/getUserUPOs
request to retrieve a list of their stored UPOs. - Display these UPOs for the customer to choose from, (also display the option to choose another account).
- If the customer decides not to use one of their stored UPOs, by instead wants to enter a different bank account, then skip back to the For a new customer step.
- If the customer selects one of their previously stored UPOs to pay from, then:
- Send a
/payment
request. See the steps in the /payment (with UPO) section. - A successful request returns a
redirectUrl
(to an Interac Instant URL). - Redirect the customer to the
redirectUrl
address, for them to continue to the next step (choosing the Interac Instant transfer method).
- Send a
- Retrieve the customer’s
——————-
Subsequent payments to Interac Instant can be performed by sending a Payment (with UPO).
——————
Payment (with UPO)
To save your repeat-customers the effort of reentering their payment method details, you can allow them to select from one their previously stored payment methods (bank account or APM), represented by a UPO, and use it to perform the payment, as described in the suggested steps:
- Generate a
sessionToken
by sending a/getSessionToken
request. - Send a
/payment
request and include:sessionToken
userTokenId
amount
paymentOption.userPaymentOptionId
Example
/payment
with UPO Request{ "sessionToken": "1be68338-e45e-4c81-b617-e1bfb94cae3e", "merchantId": "2502136204546424962", "merchantSiteId": "126006", "userTokenId": "2J6QZH3UF9E2", "clientRequestId": "2VXORP7A1", "clientUniqueId": "695701003", "currency": "CAD", "amount": "1", "paymentOption": { "userPaymentOptionId": "8061731" }, "billingAddress": { "email": "john.smith@email.com", "country": "CA", }, "userDetails": { "country": "CA", }, "deviceDetails": { "ipAddress": "192.168.2.38" }, "urlDetails": { "notificationUrl": "[The URL to which DMNs are sent]" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example
/payment
with UPO Response{ "reason": "", "orderId": "36298951", "transactionStatus": "REDIRECT", "clientRequestId": "2VXORP7A1", "internalRequestId": 17817211, "version": "1.0", "merchantSiteId": "126006", "merchantId": "2502136204546424962", "clientUniqueId": "695701003", "errCode": 0, "paymentOption": { "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiRUM5OURFMkU0NjdBQUQ1QUU4NkQ3MzAwNjMzRkFFRTVDNTEwOEIxMjRENzI0NjgzREM5OEE1NTczMzU0NzY2NjFDNjc5MDgyMjhGMzU1NzlFQ0Y0RUUxM0QwNURGNTJGNkZCNjFFNjU5ODQxMTM3Q0Y2RjFFNjU3Nzc5MDI0MTg0NjE4NEJDODhFRjYyOUQ2MzkzQjc2NjQ3MzYwQUQxNzFDNUExQzJBNzE5MkEzMTYzMTlFQzlFNTY3MTlDQTNFODc2OUU0OTlEODRGQUZEMUZBRUM1RjUzNjEwREQ1QkIwRDU3Qjg1MUI2OUY1RjM0QzU4ODlFMUZFNERDQjI2NTAwRTFCM0VGNTA3MEJCMDAyRjg0ODM4MEI0MDMyRTBGQjY0NjY4REZDRjc4QzFFNjJBMDlERTYyMkE3RjEyNTQ0MkYzRkFFNUM1MzlGMzgwNkVGOTIwNTM0QUM4MjBFNDU0NTI1NzlERkM0OEQ3QkZBRUUyQTJERDZDQjRDMjE5RENCN0YzRjgyQ0Y2RDBGOTJGMzQ0Mjc1NjQ4REY1RDY2MEFDNUNEQ0Y2QzE4RDA2MzAzMEM5OTNEMUNBRjUyNDUyQjY1ODJGREQ0NUU4NjJEN0M0NDE3NDc1RDNFRkY0NkFCMzdDRUNGQ0NDM0U5OTA0REFERjBBNDY4QTFCNjI2NzA1MUM4OTVBOTkxNkQ0NjFCQ0I4QkQ0NkQzMDE4Mjc4RjE3NkEyOTI5MkI3OTYxQTUzNTk0RTA0NUJDM0IxMkUzOEI5MDhBRDkyQjE1NTI1QTA2QjVCQTU4NUZBOEE2MEQ4Q0VDOTRDMzBENDU0MUU2RENCRkM1NTJDMDFEMjc5RjBFMTczNTU1QTU4NEMzMDdGNEE2QTc4RjlGNEVCRTQ4OTVCRTA5MkEwQTQzMzE5OTg4ODA2MTQyQ0NCMjU1M0ZDM0JGQkI5M0ZCMTU5QjI1OUNGMzUxRjk2ODM5NDBFMzFFOTgzRUNBNDU5MEI1RkE5N0Q1MUNDMjc2MTUwQzZFM0I1NTlGODVGREQ0NTVCMjMzMEM5OEMyMzhDODUxODQ2NUNDRkJDNDIwODAwNEJCNzlGMTJFN0NDOTE2RDFDOTUwQkQ4RUQwQzJGRTNCRkVEQzUwNzMyNEYxMEMwNUY4NDIzQzI1MEIxMEEwRTFCMEY3OTU1NEJCMTU4N0QzMkQ5QzVDN0NGQ0Y2NTc4RTkwRTFEQUQ4NDY3Mzc2MzJGMzE0MEQ1RjMyNEVCN0JGQkQ4RDYwOEE3NDk0Rjg5MUNGMTM4QzBFQjY1NkRFOUJBNjRDOTlCQ0I3NDk3MzIzMjZCOTQyMkMyM0U3OEMwQ0I3RkVCOUZGQTQ1OTI5QyIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6IjIxQzdFNzhCQTQ5MTUyMzFGNTM1QkEzMDBGNjA3OUJDIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.oJcwsoVB8wQXXNGi71Diqb3Lhm_6Vj3b5elO9w2ya67iG6IXP0jcFRWssBldiFvqlszE0t0GyEjgllvoZqXejt7GqcGmpUrGuJjrJL7T6yvnv15ApKSSNOKC_O2Q2yxU5l1IxHpY7vWkl3__oDJ0zMEjCyK4czW_B63-ZaGplfI0o0Mn3Aw1Vzoxn17UBjS7i4zRDm448wq2tnIfm9WBvFbR79Qdh6lJwUWI_xdwik8L3oR67MEC35w8SV9XCMjwX_WqOvaqk_mq1WXOxM0X1ooAmw6Tmd3jMM37od583ReT3GlbfDtU6NlBDAgrxEjwr807HGnQXSlKSMsxJoWnhw", "userPaymentOptionId": "8061731", "card": {} }, "sessionToken": "1be68338-e45e-4c81-b617-e1bfb94cae3e", "userTokenId": "2J6QZH3UF9E2", "status": "SUCCESS" }
——————–