Interac Withdrawal (PayPer)

Pay.Per´s Interac Withdrawal is an withdrawal banking method from Canada.

Payper’s Interac e-Transfer Payout API allows merchants to quickly disburse funds directly to their customer’s bank account in real time, including weekends.

With Interac e-Transfer Payouts, the merchant´s customers will receive an email allowing them to select their bank account and authorize the transfer.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
435	Interac Withdrawal	WithdrawnByProvider

Payment method interaction type: Request to External Payment Provider (see Interaction Types).

ProviderID: 204

After initiating the payment with Pay.per, the merchant´s customer will receive an eMail with instructions to receive their payout using their credentials.

📘
State definitions
The states listed here are still subject to change as the implementation is still in progress.

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	Descrition
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:


IP-Address (required)	The user´s IP address.

Example initiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<merchantID>TestMerchant</merchantID>
	<shopID>TestShop</shopID>
	<merchantTransactionID>2cafb1c3-4c7a-4d4e-8768-1a569c319177</merchantTransactionID>
	<paymentMethodID>435</paymentMethodID>
	<amount currencyCode="CAD">11.11</amount>
	<userID>afb6629f-0169-4777-943f-22e73a</userID>
	<userData>
		<username>afb6629f-0169-4777-943f-22e73a</username>
		<firstname>Ion</firstname>
		<lastname>Popescu</lastname>
		<currencyCode>CAD</currencyCode>
		<languageCode xsi:nil="true"/>
		<email>[email protected]</email>
		<address>
			<street>Test Street 209</street>
			<houseName xsi:nil="true"/>
			<houseNumber xsi:nil="true"/>
			<houseNumberExtension xsi:nil="true"/>
			<postalCode>T1A 0N1</postalCode>
			<city>Hamilton</city>
			<state>ON</state>
			<countryCode2>CA</countryCode2>
			<telephoneNumber>+14034881071</telephoneNumber>
		</address>
		<gender>Male</gender>
		<identificationNumberType xsi:nil="true"/>
		<drivingLicenseNumber xsi:nil="true"/>
		<drivingLicenseIssuingState xsi:nil="true"/>
	</userData>
	<userIP>10.155.19.254</userIP>
	<userSessionID>f208d795-c72f-4d22-b370-26e5a1fef27c</userSessionID>
	<creationTypeID>1</creationTypeID>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>My äüöáè payment!</value>
		</data>
	</specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse for InitiatedByProvider:

<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>435</key>
			<value>Interac Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>2cafb1c3-4c7a-4d4e-8768-1a569c319177</merchantTransactionID>
		<paymentID>3215decc-ed70-4873-875f-15e815c6b6e5</paymentID>
		<userID>afb6629f-0169-4777-943f-22e73a</userID>
		<paymentProvider>
			<key>204</key>
			<value>Payper</value>
		</paymentProvider>
		<amount currencyCode="CAD">11.11</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>10.155.19.254</userIP>
		<state>
			<id>02c34df9-7905-4c3b-9d34-4c046f0b8a73</id>
			<definition>
				<key>3</key>
				<value>InitiatedByProvider</value>
			</definition>
			<createdOn>2022-09-13T12:08:42.4213583Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">8.02</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>30678243656569432411425523055</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>1624</value>
			</detail>
			<detail xsi:type="keyBooleanValuePair">
				<key>UrgentPayment</key>
				<value>true</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentResponse>

Example initiatePaymentResponse for PendingOnProvider:

<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>XXXX</merchantID>
		<shopID>XXXX</shopID>
		<paymentMethod>
			<key>435</key>
			<value>Interac Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>2cafb1c3-4c7a-4d4e-8768-1a569c319177</merchantTransactionID>
		<paymentID>3215decc-ed70-4873-875f-15e815c6b6e5</paymentID>
		<userID>afb6629f-0169-4777-943f-22e73a</userID>
		<paymentProvider>
			<key>204</key>
			<value>Payper</value>
		</paymentProvider>
		<amount currencyCode="CAD">11.11</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>10.155.19.254</userIP>
		<state>
			<id>ea1fafbf-6640-4017-9859-d3cba1c9a62e</id>
			<definition>
				<key>120</key>
				<value>PendingOnProvider</value>
			</definition>
			<createdOn>2022-09-13T12:08:42.4213583Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">8.02</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>30678243656569432411425523055</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>1624</value>
			</detail>
      <detail xsi:type="keyBooleanValuePair">
				<key>UrgentPayment</key>
				<value>false</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentResponse>

Example initiatePaymentResponse for an error state

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>XXXX</merchantID>
		<shopID>XXXX</shopID>
		<paymentMethod>
			<key>435</key>
			<value>Interac Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>25a199b7-fcd2-4330-84eb-8f44455db07b</merchantTransactionID>
		<paymentID>5a05d570-d19f-4cd6-8ff6-af2830350321</paymentID>
		<userID>f5074d2c-748a-4951-826b-54d6c6</userID>
		<paymentProvider>
			<key>204</key>
			<value>Payper</value>
		</paymentProvider>
		<amount currencyCode="CAD">20.10</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>4eee951d-ac1a-4b0c-b5f8-c33ed349364b</id>
			<definition>
				<key>4</key>
				<value>InitiateErrorReportedByProvider</value>
			</definition>
			<createdOn>2022-09-13T11:32:43.2177083Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">14.52</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>1581</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentResponse>

Possible payment details in initiatePaymentResponse:


ProviderTransactionID	TransactionID at provider
ProviderExternalID	ProviderExternalID sent by PXP to provider
UrgentPayment	Field to return the customer´s auto deposit status.

📘
UrgentPayment
This field will return the customer´s auto deposit status and show if the payment is processed immediately or with a delay.
The possible values are "true" or "false" (boolean).
True is returned if Payper can confirm that at the time of the request that this customer has auto deposit enabled. In some cases this only indicates a high likelihood that the customer has auto deposit enabled.
False is returned if Payper can confirm that at the time of request that this customer does not have auto deposit enabled, or when Payper cannot query the status of the auto deposit at this time.

Possible payment states in initiatePaymentResponse:

Payment State	Description
InitiatedByProvider (3)	OK state; the payment has been initiated by PayPer.
PendingOnProvider (120)	Intermediate state
InitiateErrorReportedByProvider (4)	Error state; Technical error during payment initialization. Final state.
InitiateRequestProviderCommunicationErrorOccured (325)	Technical communication error state. Final state.
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 with 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>435</key>
		<value>Interac Withdrawal</value>
	</paymentMethod>
	<merchantTransactionID>9480359b-05b9-4dc7-9897-96ded2dc26fa</merchantTransactionID>
	<paymentID>a32833ca-5f65-44a9-8442-dc2002b3bc6f</paymentID>
	<userID>a92f94cf-3c60-426a-b763-5d3778</userID>
	<paymentProvider>
		<key>204</key>
		<value>Payper</value>
	</paymentProvider>
	<amount currencyCode="CAD">13.92</amount>
	<creationType>
		<key>1</key>
		<value>User</value>
	</creationType>
	<userIP>10.155.19.254</userIP>
	<state>
		<id>d2592468-063a-443d-b243-7435ebd6a2ea</id>
		<definition>
			<key>225</key>
			<value>ValidationFailed</value>
		</definition>
		<createdOn>2023-03-28T10:29:33.5662887Z</createdOn>
		<paymentStateDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderErrorResponseCode</key>
				<value>1115</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderErrorResponseMessage</key>
				<value>invalid ip address!</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">10.05</baseAmount>
	<paymentDetails>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderExternalID</key>
			<value>57495</value>
		</detail>
	</paymentDetails>
</payment>
</initiatePaymentResponse>

📘
Possible duplication of InitiatedByProvider state in initiatePaymentResponse and notification
The state InitiatedByProvider will be returned in the initiatePaymentResponse and also in the handlePaymentStateChangedNotification.
There 2 options:
a) The Interac Withdrawal will be processed without a delay by Pay.per.
The initiatePaymentResponse will list the state InitiatedByProvider and a handlePaymentStateChangedNotification for InitiatedByProvider will also be sent.
Alternatively, the initiatePaymentResponse will include an error, such as ValidationFailed or InitiateRefusedByProvider
b) The Interac Withdrawal will be batched and processed with a delay.
The initiatePaymentResponse will include the state PendingOnProvider. Later the state InitiatedByProvider will be notified to the merchant in the handlePaymentStateChangedNotificiation.
If an error occurs, it is possible that after the state PendingOnProvider an error state - such as ValidationFailed- will be notified in the handlePaymentStateChangedNotification.

After the withdrawal has been initiated with PayPer, a notification is being sent from Payper to PXP Financial.

This state is an intermediate state:

Payment state	Description
PendingOnCustomer	Payout has been sent, waiting for customer to accept.

These states below are final states:

Payment State	Description
WithdrawnByProvider (20)	The payment was completed successfully. Customer has successfully deposited their payout.
Expired (102)	Customer did not deposit their payout and it has expired. An eTransfer withdrawal will expire 30 days from midnight UTC the following day.
AbortedByCustomer (101)	Payout has been declined by the customer.
AbortedByProvider (352)	Payout was returned - customer did not receive the funds.
Aborted (524)	Payment called by merchant or by PayPer on behalf of the merchant.

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Provider Testing

Please test with amounts ending as follows:

xx.00 state WithdrawnByProvider (webhook claimed)
xx.13 state AbortedByCustomer (declined)
xx.44 state AbortedByProvider (returned)
xx.55 state AbortedByProvider (failed)
xx.66 state Aborted (cancelled)
xx.99 state Expired (expired)

Interac Withdrawal (PayPer)

📘
State definitions

Redirect Integration

Backend2BackendIntegration

📘
UrgentPayment

📘
Possible duplication of InitiatedByProvider state in initiatePaymentResponse and notification

Notifications

Provider Testing

📘State definitions

Redirect Integration

Backend2BackendIntegration

📘UrgentPayment

📘Possible duplication of InitiatedByProvider state in initiatePaymentResponse and notification

Notifications

Provider Testing

📘
State definitions

📘
UrgentPayment

📘
Possible duplication of InitiatedByProvider state in initiatePaymentResponse and notification