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

1. 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.
2. Generate a sessionToken by sending a /getSessionToken request.
3. 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).

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

   1. 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.
   2. Interac Instant processes the request in near-realtime.
      During testing, you need to contact Nuvei to simulate the transaction processing and provide you with a simulated transaction response.

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

   1. The system displays the payment details and APMReferenceID, as well as instructions for the customer to complete the transaction.
      
      Example Interac e-Transfer Transfer
      
      You receive a DMN with “status=PENDING”. The transaction remains in this status until it is either APPROVED or DECLINED.

   2. The customer follows the instructions, for example:
      1. To log in to their bank account website or app, and copy the unique payment details displayed, into their bank page.
      2. 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.
   3. 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 a status of either:
      • APPROVED – You receive a DMN with “status=APPROVED“.
      • DECLINED – You receive a DMN with “status=DECLINED“.
        The process ends here!
        
6. 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 customer
   • userPaymentOptionId (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

1. The Interac Instant Payout flow begins when you want to pay money into the customer’s bank account.
2. 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.
3. Send the customer’s userTokenId in a /getUserUPOs request to retrieve a list of their UPOs (and their security questions).
4. Display these UPOs for the customer to choose from (also display the option to choose another account).
5. Handle the customer’s selection:
   1. If the customer selects one of their previously stored UPOs for you to pay the money into, then:
      1. 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
      2. If the selected UPO does not have a security question, then add a UPO security question.
   2. 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.
6. Now that you have a UPO that contains a security question, use the relevant userTokenId and userPaymentOptionId 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"
   }

7. 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 and Status=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:

1. If your customer does not yet have a userTokenId, then generate one by sending a customer identifier, from your system, in a /createUser request.
2. Send the customer’s userTokenId in an /addUPOAPM request, and include the following additional Interac Instant parameters in an apmData block:
   • interac_instant_email
   • interac_instant_phone (Canadian phone 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 (Canadian phone 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"
}