Payper´s Interac deposit is an online banking payment method from Canada. Payer’s API integration makes it easy to accept Interac e-Transfer payments from any Canadian bank account. Canadian bank account holders authorize payments directly from their bank account. With Interac e-Transfer the merchant´s customers receive an email allowing them to send the payment through the Interac network by logging into their bank account and authorizing the transfer. The merchant will send an **initiatePaymentRequest** to PXP and in the response a URL will be shared, to which the customer should be redirected to complete the payment with their banking credentials. The following method IDs are covered in this section: | ID | Name | Credit/Debit State | | :-- | :---------------------------- | :----------------------- | | 343 | **Interac eTransfer Deposit** | DepositedByProvider (29) | Payment method interaction type: Redirection to External Payment Provider (see [Interaction Types](doc:interactions-merchantkalixaprovider)). After initiating the payment with Payper, the customer is redirected to a online banking selection page. ## Guidelines > 📘 Merchant cashier > > Please pay attention to the user interface [guidelines regarding popup blocking](https://docs.payper.ca/docs/payment-flows#handling-browser-pop-up-blocking) from Payper. > > Please consider also passing a returnURL in parameter **HomePageUrl** as described below as this should also improve the success rate. In the **initiatePaymentResponse** a parameter **BrowserRedirect** will indicate if the user should be redirected in a pop-up or without a pop-up. In the later case, the customer will be redirected back to the merchant. > 🚧 Note to existing merchants > > The payment detail **BrowserRedirect** is only returned upon activation request to PXP. > > Once enabled, it will be always returned, regardless if the merchant will send an URL in the **HomePageUrl** field, with the default value being _false_ (for merchant to open a pop-up). > 📘 Limitation and expiry of payments > > Payper allows the end customer to only initiate 3 deposits at once. > > This limit is set by Payper and is designed to keep customers from initiating deposit requests with no intention of completing them. The number of pending deposits can be increased by Payper on demand. > > Please keep in mind that after 24 hours the transaction will automatically expire and the customer can then initiate new transactions even if they did not complete or decline the transaction. > > Payper will also send out an email to customers that hit this limit explaining to them that they can compete or decline the pending transaction if they would like to initiate a new one. ## Redirect Integration Not supported at this moment. ## Backend2BackendIntegration ### Payment Initiation The merchant needs to ensure to include an **user** in the _initiatepaymentRequest_ with the following data: | User.data | Description | | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **eMail** (required) | The customer´s eMail address. | | **phone** (required) | The customer´s phone number. Please use this format: "+14034881071" | | **FirstName** (required) | The customer´s first name. | | **LastName** (required) | The customer´s last name | | **Address.Street** (required) | The customer´s street address. | | **Address.City** (required) | The customer´s city. | | **Address.State** (required) | The customer´s state in ISO format, e.g. "Alberta" | | **Address.Country** (required) | The customer´s country. | | **Address.postal_code** (required) | The customer´s zip code, either 5-digit zip code for US customer (e.g. "12345") or 6-character alphanumeric postal code (e.g. "A1A 1A1") for Canadian customers | The following data needs to be passed as well: | key (value type, account type, required) | Value | | :--------------------------------------- | :--------------------- | | **userIP** (required) | The user´s IP address. | The following data can be passed optionally: | key (value type, account type, required) | Value | | :--------------------------------------- | :------------------------------------------------------------------- | | **HomePageUrl** (optional) | URL to redirect the customer back to after the payment is completed. | > ❗️ No redirection on provider´s sandbox > > On Payper´s sandbox the user is not redirected back to the merchant´s website. This is a limitation from Payper. > > In LIVE/production the user is redirected back to the merchant. **Example initiatePaymentRequest:** ```xml TestMerchant TestShop OB-20220130-1333 343 11.01 OB-20220930-1349 username01 John Doe CAD john.doe@example.com

123 home street M4R 2G8 Toronto Ontario CA +16479325666

Male 127.0.0.22 08b980b9-b5be-4d0a-9e1b-a6541d6ac9ce 1 HomePageUrl https://apple.com ``` > 📘 User Details > > Please make sure to provide all required fields on the user passed in the initiatePayment request. **Example initiatePaymentResponse:** ```xml TestMerchant TestShop 343 Interac eTransfer Deposit OB-20220130-1333 93a44ce9-75d4-4049-bece-b08e4cfc23ae OB-20220930-1349 204 Payper 11.01 1 User 127.0.0.22 ff0e9bd5-1c80-4346-b749-6b96a6067e21 30 RedirectURLCreated 2023-01-30T12:37:06.1895454Z RedirectionUrl https://sandbox.interac.payper.ca/eTransfer/30899813071920313922398821651 PaymentStateReasonID 1 false 7.95 ProviderTransactionID 30899813071920313922398821651 BrowserRedirect true ProviderExternalID 42787 ```
**Possible payment details in initiatePaymentResponse**:

key (value type, account type, required)	Value
ProviderTransactionID	TransactionID from Payper
ProviderExternalID	TransactionID from PXP Financial
BrowserRedirect (boolean)	* _false _indicates that the merchant should open a pop-up with the RedirectionURL. * _true _indicates that the merchant should redirect the customer to the RedirectionURL. After the payment is completed, the user will be redirected back to the URL passed in the HomePageUrl field.The default value for this field is false.Note: Payper determines if a page redirect or a popup is to be used depending on the user´s email address.

**Possible payment states in initiatePaymentResponse:**

Payment State	Description
RedirectURLCreated (30)	OK state; Redirect user to the URL The merchant system should retrieve the redirect URL from the key RedirectionUrl
InitiateErrorReportedByProvider (4)	Error state; Technical error during payment initialization. Final state.
InitiateRequestProviderCommunicationErrorOccured (325)	Technical communication error state. Final state, however update to
InitiateRefusedByProvider (550)	Generic provider decline
ValidationFailed (225)	Error state returned if submitted data is incorrect. Incorrect field information will be returned in _ProviderErrorResponseCode_, _ProviderErrorResponseMessage_and _ProviderResponseMessageAdvice_

### Optional integration with Real Time Payment Interface Merchant may optionally render the Socket page inside their checkout by embedding that page within a iFrame or WebView. Merchant should call [https://**hostname**/**txn**/**amount**/**format**?env=**env]()** e.g. [https://socket-server-sandbox.payper.ca/32685098422147240111389325650/20.00/html?env=web]() | Parameter | Source | Description | | :--------- | :--------------------------------------------------------------------------------- | :-------------------------------------------------- | | **host** | [https://socket-server-sandbox.payper.ca](https://socket-server-sandbox.payper.ca) | ProviderTransactionID | | **txn** | from **ProviderTransactionID** from paymentDetails | ProviderTransactionID | | **amount** | from **amount** in CAD | Transaction amount in CAD in the form of e.g. 25.00 | | **format** | merchant provided response type - plain text, HTML or JS enabled HTML | either "html", "js" or "text" | | **env** | merchant provided environment parameter to specific display environment | either "web", "ios" or "android" | The interface will automatically connect to Payper socket server, will display live transaction progress and update the UI as the eTransfer payment completes. Merchant should check that * Front end successfully connects to Payper socket server using the provided key * Real time messages are displayed consistently during transaction flows * iFrame integration accurately reflects transaction states such as pending, approved and failed * Event messages are displayed with minimal latency * Dynamic UI updates mirror back end payment state (from notifications received from PXP) ### Additional responses **Sample InitiatePaymentResponse in state ValidationFailed**: ```xml xml B2BTestMerchant PayperMockShop 343 Interac eTransfer Deposit 753ea171-bedb-4ab7-a2c5-c0ecd49d627a 87db4650-b67f-4d4a-ad45-51322355f9fe ed629fa9-9d9d-469b-ab66-5c710a 204 Payper 104.01 1 User 127.0.0.1 51841cde-ee23-45a0-ba7c-e05dfe339946 225 ValidationFailed 2023-03-28T10:42:36.6071635Z ProviderErrorResponseCode 1116 ProviderErrorResponseMessage udf1 must be unique! ProviderResponseMessageAdvice Sorry your request was declined!, please contact support for more information. PaymentStateReasonID 1 false 75.11 ProviderExternalID 57503 ``` After redirection of the customer to Payper, a notification is being sent from Payper to PXP Financial. Transition from redirect to final (success) state could take from a few seconds up to 24 hours. ### Intermediate and final states These states below are intermediate states. They can be notified at the merchant´s wish. | Payment State | Description | | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **PendingOnCustomer** | The Interac system is waiting for the customer to complete the transaction | | **PendingOnProvider** | Provider is waiting for Interac to confirm funds to Payper´s account. This state only appears if there is a block with the bank and this doesn´t happen for every transaction. | These states below are final states: | Payment State | Description | | :--------------------------- | :------------------------------------------------------------------------------------------------------------------- | | **DepositedByProvider** (29) | The payment was reported as successful by the provider. | | **RefusedByProvider** (100) | The payment has been declined. | | **Expired** (102) | The payment request has expired. Interac eTransfer payment will expire 24 hours from midnight UTC the following day. | | **Aborted** (524) | The payment has been cancelled by the merchant or by PayPer on behalf of the merchant. | > 📘 Expiry > > An Interac eTransfer payment will expire 24 hours from midnight UTC the following day. > > For example, if an Interac eTransfer transaction is created at September 16th at 21:00 UTC, it will expire 24 hours from September 17th 00:00UTC so on September 18th at 00:00 UTC ### Payment details When enabled by Payper, it will be possible to receive another update in state **PaymentDetailsUpdated** with the details **BankName** and **PayerName**. | PaymentDetail | Description | | :------------ | :---------------------------------------------------------------------- | | **BankName** | The name of the bank from which the deposit was credited. | | **PayerName** | The name of the payer from which bank account the deposit was credited. | > ❗️ BankName and PayerName > > Please note, depending on the data delivered by Payper, either BankName or PayerName or both might be empty. > 📘 PaymentDetailUpdate > > The payment state ID for PaymentDetailsUpdated is **633**. **handlePaymentStateChangedNotification** with BankName and PayerName: ```xml xxxx xxxx 343 Interac eTransfer Deposit a635736d-9e66-42cf-a673-89c7bd4b3850 94d238e4-ef75-4a22-af91-f1c178620bd8 ba2f25b9-4c4e-451b-82c8-4fdf2d 204 Payper 123.0100 1 User 127.0.0.1 e92fca2e-a195-44ed-8d01-b52de6efd479 633 PaymentDetailsUpdated 2022-09-23T08:03:38.943 PaymentStateReasonID 1 false 88.8400 ProviderExternalID 6981 ProviderTransactionID 5659879136449473 BankName Bank of Canada PayerName Tasty Sort ``` **handlePaymentStateChangedNotification** with only PayerName: ```xml XXXXXX XXXXX 343 Interac eTransfer Deposit c79f8d59-3456-44fc-8eb6-f89898964426 e97e12bd-db85-4f3e-a5f7-7c460d823408 26c2bb10-d3ad-438f-b173-186559 204 Payper 124.0100 1 User 127.0.0.1 44f398ea-b518-4bde-a42e-66907005ace0 633 PaymentDetailsUpdated 2022-09-23T08:03:47.083 PaymentStateReasonID 1 false 89.5600 ProviderExternalID 6982 ProviderTransactionID 3252635514511482 PayerName Tasty Sort ``` ## Notifications The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see [PaymentStateChangedNotification](doc:paymentstatechangednotification). **Example handlePaymentStateChangedNotificationRequest:** ```xml B2BTestMerchant PayperMockShop 343 Interac eTransfer Deposit b3caacef-6d69-4a0a-a433-b5671d5f0327 f8d28ad0-b76d-4f2a-8f01-2df51489b741 9ee34ebb-2908-4bcb-bb47-901847 204 Payper 110.0100 1 User 127.0.0.1 ab8aced8-7ec0-489f-af3b-dd6bb2aeac68 29 DepositedByProvider 2022-09-12T07:35:56.413 true 79.4500 ProviderExternalID 614 ProviderTransactionID 6c759780-5ca0-4377-a8f2-6ac7e6950622 ``` ## Provider Testing During provider testing, the following amounts will return the following statuses: | Amount | Description | | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | | xx.00 (xx is between 0 and 2899) | Results in a payment in DepositedByProvider ("approved" on provider side) | | xx.13 (xx is between 0 and 2899) | Results in a payment in RefusedByProvider state ("declined" on provider side) | | xx.66 (xx is between 0 and 2899) | Results in a payment in Aborted state ("canceled" on provider side) | | 88.88 | Results in a payment in InitiateErrorReportedByProvider state ("declined" on provider side) | | xx.99 (xx is between 0 and 2899) | Results in a payment in Expired state ("expired" on provider side) | | Amounts between 2900 and 3000 CAD | This will result in state InitiateErrorReportedByProvider ("declined" on provider side) | | Amounts above 3000 CAD | This will result in state ValidationFailed ("pl_error" on provider side) | | Requests with incorrect data, eg. an invalid zip code (postal code). | This will result in ValidationFailed state ("invalid" on provider side) | ## Out of band transaction The payment method will also include support for out of band transactions. In the event that a customer who has previously transacted via Interac e-Transfer performs additional deposits directly through a stored payee in their online banking, without processing through a merchant's system, Payper will automatically identify these payment and a new transaction will be created in the system and will be notified to PXP. PXP will create new transactions and notify those to the merchant. Alternatively Payper can automatically refund these payments and return the funds to the sender. **handlePaymentStateChangedNotification** for an out of band transaction. Such a transaction will automatically include the details **BankName** and **PayerName**: ```xml TestMerchant TestShop 343 Interac eTransfer Deposit de51b580-314a-4d6b-8dd4-dcbee3d6bf2f 39491938-ae90-402a-bf13-fb487ccb091f 5ab0e8a6-3313-4675-89ff-6fdfe9 204 Payper 220.1000 0.0000 6 Provider 127.0.0.1 485b81f7-4b8a-4423-a84f-cac5310bd888 29 DepositedByProvider 2022-09-22T14:32:38.937 true 158.9500 BaseShopFeeAmount 0.0000 BaseShopFeeCurrencyCode EUR ProviderExternalID 6683 ProviderTransactionID 346344390 BankName Toronto-Dominion Bank PayerName payper user ```