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 real-time.
• 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 alternative payment method (APM) 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 setup prerequisites, and are ready to integrate Interac Instant 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”.
• A UPO 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

Payment (Deposit) Flow

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

• userTokenId
• amount
• currency
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_INTERAC_Instant“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName, email, phone, country
• userDetails class containing: firstName, lastName, email, phone, country
  
  Canadian phone numbers must be 10 digits, not including the country prefix.

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"
    }
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "phone": "16139575555",
    "country": "CA",
    "email": "[email protected]"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "phone": "16139575555",
    "country": "CA",
    "email": "[email protected]"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

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"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to the URL provided in urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

If the payment is successful, then the Nuvei system generates and returns 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 – Representing the customer’s bank account.

Payout (Withdrawal) Flow

Interac Instant allows you to pay money to your customers using the /payout REST API method.

A /payout request requires userPaymentOptionId, 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

Follow these steps to perform a payout (withdrawal):

1. 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.
2. Send the customer’s userTokenId in a /getUserUPOs request to retrieve a list of their UPOs (and their security questions).
3. Display these UPOs for the customer to choose from (also display the option to choose another account).
4. 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.
5. 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

   The format of clientUniqueId must be as follows: ^[0-9a-zA-Z_-]{1,50}$.

   {
     "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": "<UPO received from previous deposit>"
     },
     "deviceDetails": {
       "ipAddress": "<customer's IP address>"
     },
     "urlDetails": {
       "notificationUrl": "<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"
   }

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

Online Banking

1. The customer is redirected to the redirectUrl address.
2. The user selects the Online Banking option and then selects their bank.
   
3. The user can use biometrics via their bank’s app for fast login:
   
4. All the payment details are prefilled. The user selects their bank account for the payment.
   
5. The user receives a confirmation message.
   

e-Transfer

1. The customer is redirected to the redirectUrl address.
2. The user selects the e-Transfer option.
   
3. The bank’s page displays the payment details and instructions for the customer to complete the transaction.
   
4. The user sends an e-Transfer request.
   
5. The user receives a confirmation message.
   

Testing

Data	Value
First Name	Larry
Last Name	Johnson
Email Address	Any valid email address Example: [email protected]
Phone Number	Any 10-digit number Example: 16139575555

Appendices

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, including the following Interac Instant parameters in the apmData class:
   • interac_instant_email
   • interac_instant_phone (Canadian phone numbers must be 10 digits, without the country prefix.)
   • 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": "[email protected]",
    "interac_instant_phone": "16139575555",
    "interac_instant_security_question": "your favorite city",
    "interac_instant_security_answer": "boston"
  },
  "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, which is stored in your system, in an /editUPOAPM request and include the following additional Interac Instant parameters in the apmData class:

• interac_instant_email
• interac_instant_phone (Canadian phone numbers must be 10 digits, without the country prefix.)
• 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": "[email protected]",
    "interac_instant_phone": "16139575555",
    "interac_instant_security_question": "your favorite city",
    "interac_instant_security_answer": "<boston>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

Example /editUPOAPM Response

{
  "reason": "",
  "merchantId": "2502136204546424962",
  "errCode": 0,
  "clientRequestId": "HWMTWQ2RT",
  "internalRequestId": 17817221,
  "version": "1.0",
  "status": "SUCCESS",
  "merchantSiteId": "126006"
}