Interac eTransfer Deposit (Paybilt)
Paybilt´s Interac deposit is an online banking payment method from Canada.
Paybilt´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).
ProviderID: 204
Provider PayPer
On transactions with Paybilt the provider returned by PaymentService is still "PayPer", but the transactions are sent to a different endpoint URL and a different set of credentials will be used.
After initiating the payment with Paybilt, the customer is redirected to a online banking selection page.
Guidelines
Merchant cashier
Please pay attention to the user interface from Paybilt.
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
Paybilt allows the end customer to only initiate 3 deposits at once.
This limit is set by Paybilt 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 Paybilt 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.
Paybilt 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
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 Paybilt´s sandbox the user is not redirected back to the merchant´s website. This is a limitation from Paybilt.
In LIVE/production the user is redirected back to the merchant.
Example initiatePaymentRequest:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>TestMerchant</merchantID>
<shopID>TestShop</shopID>
<merchantTransactionID>OB-20220130-1333</merchantTransactionID>
<paymentMethodID>343</paymentMethodID>
<amount currencyCode="CAD">11.01</amount>
<userID>OB-20220930-1349</userID>
<userData>
<username>username01</username>
<firstname>John</firstname>
<lastname>Doe</lastname>
<currencyCode>CAD</currencyCode>
<email>[email protected]</email>
<address>
<street>123 home street</street>
<postalCode>M4R 2G8</postalCode>
<city>Toronto</city>
<state>Ontario</state>
<countryCode2>CA</countryCode2>
<telephoneNumber>+16479325666</telephoneNumber>
</address>
<gender>Male</gender>
</userData>
<userIP>127.0.0.22</userIP>
<userSessionID>08b980b9-b5be-4d0a-9e1b-a6541d6ac9ce</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>HomePageUrl</key>
<value>https://apple.com</value>
</data>
</specificPaymentData>
</initiatePaymentRequest>
User Details
Please make sure to provide all required fields on the user passed in the initiatePayment request.
Example initiatePaymentResponse:
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>TestMerchant</merchantID>
<shopID>TestShop</shopID>
<paymentMethod>
<key>343</key>
<value>Interac eTransfer Deposit</value>
</paymentMethod>
<merchantTransactionID>OB-20220130-1333</merchantTransactionID>
<paymentID>93a44ce9-75d4-4049-bece-b08e4cfc23ae</paymentID>
<userID>OB-20220930-1349</userID>
<paymentProvider>
<key>204</key>
<value>Payper</value>
</paymentProvider>
<amount currencyCode="CAD">11.01</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.22</userIP>
<state>
<id>ff0e9bd5-1c80-4346-b749-6b96a6067e21</id>
<definition>
<key>30</key>
<value>RedirectURLCreated</value>
</definition>
<createdOn>2023-01-30T12:37:06.1895454Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://sandbox.interac.payper.ca/eTransfer/30899813071920313922398821651</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">7.95</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>30899813071920313922398821651</value>
</detail>
<detail xsi:type="keyBooleanValuePair">
<key>BrowserRedirect</key>
<value>true</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>42787</value>
</detail>
</paymentDetails>
</payment>
</initiatePaymentResponse>
Possible payment details in initiatePaymentResponse:
| key (value type, account type, required) | Value |
|---|---|
| ProviderTransactionID | TransactionID from Paybilt |
| 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: Paybilt 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 |
Sample InitiatePaymentResponse in state ValidationFailed:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns=http://www.cqrpayments.com/PaymentProcessing>
<payment
xsi:type="paymentWithPaymentAccount">
<merchantID>B2BTestMerchant</merchantID>
<shopID>PayperMockShop</shopID>
<paymentMethod>
<key>343</key>
<value>Interac eTransfer Deposit</value>
</paymentMethod>
<merchantTransactionID>753ea171-bedb-4ab7-a2c5-c0ecd49d627a</merchantTransactionID>
<paymentID>87db4650-b67f-4d4a-ad45-51322355f9fe</paymentID>
<userID>ed629fa9-9d9d-469b-ab66-5c710a</userID>
<paymentProvider>
<key>204</key>
<value>Payper</value>
</paymentProvider>
<amount currencyCode="CAD">104.01</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>51841cde-ee23-45a0-ba7c-e05dfe339946</id>
<definition>
<key>225</key>
<value>ValidationFailed</value>
</definition>
<createdOn>2023-03-28T10:42:36.6071635Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderErrorResponseCode</key>
<value>1116</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderErrorResponseMessage</key>
<value>udf1 must be unique!</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseMessageAdvice</key>
<value>Sorry your request was declined!, please contact support for more information.</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">75.11</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>57503</value>
</detail>
</paymentDetails>
</payment>
</initiatePaymentResponse>
After redirection of the customer to Paybilt, 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.
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 | Paybilt is waiting for Interac to confirm funds to Paybilt´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 Paybilt 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 Paybilt, 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 Paybilt, either BankName or PayerName or both might be empty.
PaymentDetailUpdate
The payment state ID for PaymentDetailsUpdated is 633.
handlePaymentStateChangedNotification with BankName and PayerName:
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>xxxx</merchantID>
<shopID>xxxx</shopID>
<paymentMethod>
<key>343</key>
<value>Interac eTransfer Deposit</value>
</paymentMethod>
<merchantTransactionID>a635736d-9e66-42cf-a673-89c7bd4b3850</merchantTransactionID>
<paymentID>94d238e4-ef75-4a22-af91-f1c178620bd8</paymentID>
<userID>ba2f25b9-4c4e-451b-82c8-4fdf2d</userID>
<paymentProvider>
<key>204</key>
<value>Payper</value>
</paymentProvider>
<amount currencyCode="CAD">123.0100</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>e92fca2e-a195-44ed-8d01-b52de6efd479</id>
<definition>
<key>633</key>
<value>PaymentDetailsUpdated</value>
</definition>
<createdOn>2022-09-23T08:03:38.943</createdOn>
<paymentStateDetails>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">88.8400</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>6981</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>5659879136449473</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>BankName</key>
<value>Bank of Canada</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayerName</key>
<value>Tasty Sort</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
handlePaymentStateChangedNotification with only PayerName:
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>XXXXXX</merchantID>
<shopID>XXXXX</shopID>
<paymentMethod>
<key>343</key>
<value>Interac eTransfer Deposit</value>
</paymentMethod>
<merchantTransactionID>c79f8d59-3456-44fc-8eb6-f89898964426</merchantTransactionID>
<paymentID>e97e12bd-db85-4f3e-a5f7-7c460d823408</paymentID>
<userID>26c2bb10-d3ad-438f-b173-186559</userID>
<paymentProvider>
<key>204</key>
<value>Payper</value>
</paymentProvider>
<amount currencyCode="CAD">124.0100</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>44f398ea-b518-4bde-a42e-66907005ace0</id>
<definition>
<key>633</key>
<value>PaymentDetailsUpdated</value>
</definition>
<createdOn>2022-09-23T08:03:47.083</createdOn>
<paymentStateDetails>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">89.5600</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>6982</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>3252635514511482</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayerName</key>
<value>Tasty Sort</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
Notifications
The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.
Example handlePaymentStateChangedNotificationRequest:
<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>B2BTestMerchant</merchantID>
<shopID>PayperMockShop</shopID>
<paymentMethod>
<key>343</key>
<value>Interac eTransfer Deposit</value>
</paymentMethod>
<merchantTransactionID>b3caacef-6d69-4a0a-a433-b5671d5f0327</merchantTransactionID>
<paymentID>f8d28ad0-b76d-4f2a-8f01-2df51489b741</paymentID>
<userID>9ee34ebb-2908-4bcb-bb47-901847</userID>
<paymentProvider>
<key>204</key>
<value>Payper</value>
</paymentProvider>
<amount currencyCode="CAD">110.0100</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>ab8aced8-7ec0-489f-af3b-dd6bb2aeac68</id>
<definition>
<key>29</key>
<value>DepositedByProvider</value>
</definition>
<createdOn>2022-09-12T07:35:56.413</createdOn>
<paymentStateDetails xsi:nil="true" />
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">79.4500</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>614</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>6c759780-5ca0-4377-a8f2-6ac7e6950622</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
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, Paybilt 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 Paybilt 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 version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>TestMerchant</merchantID>
<shopID>TestShop</shopID>
<paymentMethod>
<key>343</key>
<value>Interac eTransfer Deposit</value>
</paymentMethod>
<merchantTransactionID>de51b580-314a-4d6b-8dd4-dcbee3d6bf2f</merchantTransactionID>
<paymentID>39491938-ae90-402a-bf13-fb487ccb091f</paymentID>
<userID>5ab0e8a6-3313-4675-89ff-6fdfe9</userID>
<paymentProvider>
<key>204</key>
<value>Payper</value>
</paymentProvider>
<amount currencyCode="CAD">220.1000</amount>
<shopFee currencyCode="CAD">0.0000</shopFee>
<creationType>
<key>6</key>
<value>Provider</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>485b81f7-4b8a-4423-a84f-cac5310bd888</id>
<definition>
<key>29</key>
<value>DepositedByProvider</value>
</definition>
<createdOn>2022-09-22T14:32:38.937</createdOn>
<paymentStateDetails xsi:nil="true" />
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">158.9500</baseAmount>
<paymentDetails>
<detail xsi:type="keyDecimalValuePair">
<key>BaseShopFeeAmount</key>
<value>0.0000</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>BaseShopFeeCurrencyCode</key>
<value>EUR</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>6683</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>346344390</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>BankName</key>
<value>Toronto-Dominion Bank</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayerName</key>
<value>payper user</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
Updated 7 days ago