When the Consumer initiates a payment, their web browser is redirected to the payment URL. The payment redirect request parameters identify the Merchant and Consumer and specify the details of the payment transaction.

Data Exchange Message Definitions

There are several types of messages that pass data between Paramount and the Merchant system during a payment transaction. These messages are described in data exchange message definitions below.

Message type	Description
Payment Redirect Request	Contains the information required to process a payment. This message is sent to Paramount when the Consumer is redirected by the Merchant system.
Payment Redirect Response	This message is sent to the Merchant system when the Consumer is redirected back to the Merchant at the end of the payment transaction.
Payment Notification	Contains the results of the payment. This message is sent from the Paramount system to the transaction notification URL provided by the Merchant during the integration.
Verification Request	Confirms that the Merchant has received either a payment notification or an event notification. This message is sent by the Merchant system to the notification verification URL.
Verification Response	This message is sent to the Merchant system in response to the verification request.

Payment Redirect Request

When the Consumer initiates a payment, their web browser is redirected to Paramount Commerce and the payment data is provided in an HTTP POST request using the Payments API.

Parameter	Description
merchant_id	The 8-character Merchant account ID assigned by Paramount.
details	The encrypted request parameters described in Payment Redirect Request Parameters below.
iv	The HEX decimal of a random 128-bit initialization vector, which should be generated by a cryptographically secure pseudo-random number generator.

Payment Redirect Request Parameters

The parameters described in Payment redirect request parameters are included in the encrypted details parameter of the payment redirect request.

🚧
Parameters are case sensitive.

Merchants can refer to their INTERAC staging environment document for specific Merchant encryption key for their account.

Build and encode the request parameters in the application/x-www-form-urlencoded format.

merchant_id=TestMerchant&merchant_sub_id=0&merchant_user_id=CUSTOMER1&merchant_txn_num=1638830336525&txn_amount=10.00&txn_currency=CAD&first_name=Test&last_name=Customer&phone_number=6476476477&merchant_customer_email=user%40domain.com&return_url=https%3A%2F%2Fwww.paramountcommerce.com&extra_field_1=Test+Transaction

Encrypt the URL encoded request parameters using cipher AES-256/CBC/PKCS5Padding.

🚧
Amount Used in Testing INTERAC Request Money
Due to security features at partner banks, $20 cannot be used as a transaction amount when testing INTERAC Request Money payments. When testing Request Money payments, use an amount other than $20.
We recommend that you vary the test transaction amounts to reduce the likelihood of triggering a security alert.

Parameter	Type	Min Length	Max Length	Required	Description
merchant_id	String	8	8	Yes	The 8-character Merchant account ID assigned by Paramount Commerce.
merchant_sub_id	String	0	3	No	A Merchant account may be used to process transactions from multiple systems (thus require multiple notification URLs). This sub ID configured and issued by Paramount can be passed at run-time to identify a particular set of URLs.
merchant_user_id	String	4	20	Yes	The merchant-assigned unique identifier for the consumer (end user) making this transaction. This value is case-sensitive and must be consistent across all transactions for the same user.
merchant_txn_num	String	1	30	Yes	The unique Merchant assigned transaction number that identifies the payment.
txn_amount	Decimal	1	8	Yes	The payment amount. The amount must be between 1.00 and 99999.99.
txn_currency	String	3	3	Yes	The uppercase 3-letter currency code (ISO 4217).
first_name	String	1	30	Yes	The Consumer's first name.
sender_middle_name	String	0	30	No	The sender's (consumer's) middle name.
last_name	String	1	30	Yes	The Consumer's last name.
sender_dob	String (YYYY-MM-DD)	10	10	Yes	The sender's (consumer's) date of birth.
sender_street	String	1	255	Yes	The sender's (consumer's) street address.
sender_street2	String	0	255	No	The sender's (consumer's) secondary address line (e.g., apartment, suite).
sender_city	String	1	255	Yes	The sender's (consumer's) city.
sender_province	String	1	30	Yes	The sender's (consumer's) province or state.
sender_postal_code	String	6	7	Yes	The sender's (consumer's) postal code.
sender_country	String (ISO 3166-1 alpha-2)	2	2	Yes	The sender's (consumer's) country code.
sender_citizenship	String (ISO 3166-1 alpha-2)	2	2	No	The sender's (consumer's) citizenship.
phone_number	String	10	10	Yes	The Consumer's mobile phone number. This is a 3-digit area code and 7-digit local phone number.
merchant_customer_email	String	1	255	Yes	The email address associated with the Consumer's profile.
account_created_on	String (YYYY-MM-DD)	10	10	No	The date the consumer's account was created on your platform.
return_url	String	1	256	Yes	The URL where the Consumer’s browser is redirected at the end of the payment process. Merchants can include URL query string parameters, which are ignored by the Paramount system, but passed back to the Merchant system in the payment redirect response. The URL query string must be URL-encoded.
preselect_payment_flow	String	N/A	N/A	No	It is possible to create an Interac payment request loaded directly on a specific preselected payment flow, and skip the flow selection page. Reach out to your merchant Integration team or account manager to enable this functionality. Accepted Value: - `request_money`: Preselects the Interac Request Money flow. - `manual`: Preselects the manual send Interac e-transfer flow.
extra_field_1	String	0	100	No	This is a pass-through field and not recorded by Paramount. This field can be used by Merchants who want an extra parameter sent back to them in the payment notification to uniquely identify the transaction or Consumer.
receiver_first_name	String	1	30	Conditional	The receiver's first name. Required if enabled on your merchant account (e.g. remittance merchant).
receiver_middle_name	String	0	30	No	The receiver's middle name.
receiver_last_name	String	1	30	Conditional	The receiver's last name. Required if enabled on your merchant account (e.g. remittance merchant).
receiver_dob	String (YYYY-MM-DD)	10	10	Conditional	The receiver's date of birth. Required if enabled on your merchant account (e.g. remittance merchant).
receiver_street	String	1	255	Conditional	The receiver's street address. Required if enabled on your merchant account (e.g. remittance merchant).
receiver_street2	String	0	255	No	The receiver's secondary address line (e.g., apartment, suite).
receiver_city	String	1	255	Conditional	The receiver's city. Required if enabled on your merchant account (e.g. remittance merchant).
receiver_province	String	1	30	Conditional	The receiver's province or state. Required if enabled on your merchant account (e.g. remittance merchant).
receiver_postal_code	String	1	20	Conditional	The receiver's postal or ZIP code. Required if enabled on your merchant account (e.g. remittance merchant).
receiver_country	String (ISO 3166-1 alpha-2)	2	2	Conditional	The receiver's country code. Required if enabled on your merchant account (e.g. remittance merchant).
receiver_citizenship	String (ISO 3166-1 alpha-2)	2	2	No	The receiver's citizenship.
receiver_reference_number	String	1	255	Conditional	The receiver's reference account number in your records.. Required if enabled on your merchant account (e.g. remittance merchant).

QR Code Parameters

When using QR Code endpoint you can provide these optional additional parameters as part of your request.

Parameter	Type	Min Length	Max Length	Required	Description
qr_size	Number	—	—	No	Size in pixels (for both width and height). Default is 256.
qr_color	String	—	—	No	Color for the dots. Default is cobranding primary color (lightPrimaryColor / darkPrimaryColor) or black. Predefined color name or HEX.
qr_corner_color	String	—	—	No	Color for the 3 corner squares. Default is the same as qr_color. Predefined color name or HEX.
qr_background_color	String	—	—	No	Color for the background. Default is cobranding background (lightBackgroundColor / darkBackgroundColor) or white. Predefined color name or HEX.
qr_hide_logo	Boolean	—	—	No	When true, hides the logo (if cobranding is available).
qr_logo_margin	Number	—	—	No	Margin in pixels for the logo area. Default is 4.

Example Payment Request

<html>
  <head></head>
  <body>
    <form METHOD="POST" ACTION="https://staging.paydirectnow.com/consumer/interacGateway.do" >
      <input type="hidden" name="merchant_id" value="DemoOne" />
      <input type="hidden" name="details" value="3259C4EA7FC1B4F821E9696C7E57028611E7A98D841BD030258E4C293DE016F32FA424FE3B1CF783FDA2AD055240351BF389C14050C234086B3F3D742E531488D3851184AE4BB869CF1A5E9202F0113D92A26D105EBD633C124548FE137F5D218F372DDB3AE6B3665CFE12834B11DA39AC74833C0877052E5C24B3CC9EACC2F0C41AB24881C39DF5908DD07CC2C31CA9092BD029E4C0F917B1BB3337336460C4AEDD1923DB85DDC195FEC551FE33E6691CECC4613860BD019E957D2EA130AF7AECCB710C6F62AE063D38271C66BBBE898A6F583919B073507A99CCBB80CCAB6B5EF8F1601EBD68013ED31B5F7428C89785B7184C113362A8A8DFB080EBC1EA49C59AEC70E2692EF58315BA202A166A82FA0F802AD21F0190FE3246CAAA671A6E8061D3141A1C04E8BB7BD44CA12A46AF158B793545D20C736A18621117BF4307FDD2452441EC4BA886BF2C33C34C87E4339EB9907415A4A7B529BE26209D331B51B9E344382BC360A8C918514D3D627B17FA851CBC32C53AC1A287B0BB37677A307FC6175F004525E62B956493842116" />
      <input type="hidden" name="iv" value="70EC2D4955F19AD84803205C32336D9F" />
      <input type="submit" value="Interac_Payin" />
    </form>
  </body>
</html>

Payment Redirect Response

After the Paramount payment transaction is initiated and awaiting the INTERAC e-Transfer confirmation, the Consumer is redirected back to the URL provided in the return_url payment redirect request parameter. Information about the outcome of the payment transaction is not provided in the payment redirect response. Instead, this information is provided in the payment notification.

Payment Notification

After Paramount processes the payment request, it sends a payment notification to the transaction notification URL specified by the Merchant during the system integration.

📘
Notifications may take up to 48 hours to be sent to the transaction notification URL.

Payment Notification Parameters

The payment notification includes many of the same parameters included in the request, plus the transaction status, transaction fee payable by the Merchant, and any applicable payment errors.

📘
The parameters included in the payment notification may not be in the same order shown in this document.

Parameter	Type	Size	Required	Description
user_id	String	30	No	The Consumer user ID used in the Paramount system. For failed transactions, this field is blank.
txn_num	String	30	Yes	The unique transaction number created by Paramount.
txn_type	String	1	Yes	The transaction type. T: Funds transferred to Merchant
merchant_id	String	8	Yes	The 8-character Merchant account ID assigned by Paramount.
merchant_user_id	String	20	Yes	The unique Merchant-assigned Consumer user ID that was specified in the payment request.
merchant_txn_num	String	30	Yes	The Merchant-assigned transaction number that identifies the payment.
txn_amount	Decimal	(7.2)	Yes	The payment amount. The amount must be between 1.00 and 99999.99.
txn_fee	Decimal	(6.2)	Yes	The transaction fee payable by the Merchant.
txn_currency	String	3	Yes	ISO-4217 currency code of the transfer. CAD.
txn_status	String	1	Yes	The status of the payment request. A transaction notification with the final txn_status of successful (`S`) or rejected (`R`) is sent. S: Successful R: Rejected
customer_email	String	128	No	If the transaction was successful, the Consumer's INTERAC email is included in the payment notification. If the transaction was not successful, this field is empty.
error_code	String	4	No	If the payment failed, the error code is included in the response. See Payment Errors.
channel	String	1	No	The network used to settle the transaction. E: INTERAC e-Transfer transaction
extra_field_1	String	60	No	This is a pass-through field and not recorded by Paramount. This field can be used by Merchants who want an extra parameter to be sent back to them. For example, to uniquely identify the transaction or Consumer.
first_name	String	256	No	Provides merchants with the customer first name in the payment notification in the Interac payin flow. This feature is optional and will be disabled by default. Merchants can request to have this feature enabled.
last_name	String	256	No	Provides merchants with the customer last name in the payment notification in the Interac payin flow. This feature is optional and will be disabled by default. Merchants can request to have this feature enabled.
payment_flow	String	30	No	If enabled on your account, it provides the flow a user completed a payment with. `request_money`: Interac Request Money `manual`: Send Manual Interac e-Transfer
interac_reference_num	String	16	No	If enabled on your account, the reference number used to track and identify individual Interac transactions. This feature is enabled for the Request Money flow only.
counterparty_bank_name	String	256	No	If enabled on your account, the name of the financial institution of the account holder that sends the payment. This feature is enabled for the Request Money flow only.

Example Payment Notification

> txn_num=20210531124743973177000000&merchant_user_id=usr_12345&txn_fee=0.00&txn_currency=CAD&user_id=1586354379019-PS0QV937&txn_type=T&merchant_txn_num=abc12345&channel=E&error_code=&merchant_id=SmplMcht&txn_amount=30.00&customer_email=user%40domain.com&txn_status=S&extra_field_1=theextrafield&first_name=John&last_name=Doe

Payment Errors

If a payment can't be completed successfully, there are two types of codes that may be included in the payment notification: Payment request error codes and Payment result error codes.

Payment Request error codes

Payment request errors are caused by missing or invalid parameters in the payment request. These errors have codes that begin with A.

Code	Description
A001	Invalid or missing Merchant account ID (merchant_id).
A002	Generic error.
A003	Invalid Merchant sub account ID (merchant_sub_id).
A004	Invalid or missing Merchant assigned Consumer user ID (merchant_user_id).
A005	Invalid or missing Merchant transaction number (merchant_txn_num).
A006	Duplicate Merchant transaction number (merchant_txn_num).
A007	Invalid or missing transaction amount (txn_amt).
A008	Invalid or missing currency code (txn_currency).
A009	Invalid or missing first name (first_name).
A010	Invalid or missing last name (last_name).
A011	Invalid or missing return URL (return_url).
A012	Invalid or missing Consumer phone number (phone_number).
A013	Invalid or missing Merchant Consumer email (merchant_customer_email)
A014	Transaction blocked due to the consumer's geographic location
A015	Missing or invalid Sender Date of Birth (`sender_dob`).
A016	Invalid Sender Middle Name (`middle_name`).
A017	Missing or invalid Sender Street Address (`sender_street`).
A018	Invalid Sender Street Address (`sender_street2`).
A019	Missing or invalid Sender City (`sender_city`).
A020	Missing or invalid Sender Province (`sender_province`).
A021	Missing or invalid Sender Postal Code (`sender_postal_code`).
A022	Missing or invalid Sender Country (`sender_country`).
A023	Invalid Sender Citizenship (`sender_citizenship`).
A024	Missing or invalid Receiver Date of Birth (`receiver_dob`).
A025	Missing or invalid Receiver First Name (`receiver_first_name`).
A026	Invalid Receiver Middle Name (`receiver_middle_name`).
A027	Missing or invalid Receiver Last Name (`receiver_last_name`).
A028	Missing or invalid Receiver Street Address (`receiver_street`).
A029	Invalid Receiver Street Address (`receiver_street2`).
A030	Missing or invalid Receiver City (`receiver_city`).
A031	Missing or invalid Receiver Province (`receiver_province`).
A032	Missing or invalid Receiver Postal Code (`receiver_postal_code`).
A033	Missing or invalid Receiver Country (`receiver_country`).
A034	Invalid Receiver Citizenship (`receiver_citizenship`).
A035	Missing or invalid Receiver Reference Account Number (`receiver_reference_number`).
A036	Invalid Account Created On Date (`account_created_on`).

Payment Result Error Codes

If a payment can't be completed successfully, the relevant error code is included in the payment notification.

Code	Definition	Transaction fee?
1	Transaction is terminated. Transaction failed Paramount Commerce IP validation.
13	Transaction is terminated. The risk management subsystem rejected the transaction due to negative information on the bank account.	Yes
14	Transaction is terminated. The risk management subsystem returns suspicious or fraudulent information on the identity.
15	Consumer personal information mismatch.
98	Generic error.
99	The transaction is canceled by the Consumer.
101	Reference number used for INTERAC e-Transfer was previously used.
102	Amount of the INTERAC e-Transfer received doesn't match the amount specified on the Merchant website.
104	Transaction timeout / abandoned transaction.
106	Transaction was received in an unsupported language.
107	Transaction sent from a non-auto deposit bank failed.