Hosted Payment Page¶
Revision 18.6
August 18, 2022
Table of Contents
Overview¶
Payroc’s Hosted Payment Page (HPP) solution can be used in either a call centre environment or as a part of a web application.
Credit card information will be captured and stored on Payroc’s secure systems allowing merchants to accept credit card payments with minimal ongoing PCI compliance costs.
Payroc’s Tokenization solution can be included as a part of a Hosted Payment Page implementation eliminating the need to store sensitive cardholder data for future payments.
Hosted pages are integrated with merchant applications to redirect a user to Payroc’s secure environment when credit card information is to be captured.
The redirection interface allows the merchant to specify the type of transaction being requested and to automatically update their application based on the results returned by Payroc.
Processing Flow¶
Following is an overview of the transaction processing flow for hosted payment pages:
- User is redirected by the merchant application to Payroc’s secure server when card information needs to be captured
- Hosted page is opened in the user’s browser; input fields displayed on the page are determined based on the fields included in the transaction request
- User enters the card information and clicks on the Submit button.
- Validation errors, such as invalid card number, will result in the page being redisplayed so that the user can correct their entries.
- If the merchant is setup to use Payroc’s Tokenization solution and the card information is valid then a Token may be created or updated.
- If a payment amount is included with the transaction then an authorization request will be sent to the card association network.
- If the payment amount is declined by the card issuer then the payment page will re-display allowing the user to try another card.
- If the payment amount is approved then the user will be redirected to the return URL specified in the request.
- If the user clicks on the Cancel button at any time during the process then they will be redirected to the return URL specified in the transaction request.
- The response returned to the merchant application will specify whether the transaction was approved or canceled by the user.
Page Template¶
Payroc’s Hosted Payment Pages are dynamic where the elements displayed on the page are controlled based on the configuration and request fields.
The page can be configured to display a banner using an image file provided by the merchant.
Payroc will assign a URL to the page that includes a name selected by the merchant
Following is an example of a hosted page including all of the supported fields:
Message Hashing¶
The request/response messages can be verified by using the message_hash value to ensure that the message has not been altered.
The message_hash is a SHA256 HMAC of the request/response. The shared secret will be created by Payroc and provided to the merchant as part of the hosted page configuration.
Creating the hash:
- All field names and values must be URL-encoded
- Any field with empty value is dropped
- Only field names and values specified for the request type or response should be included
- message_hash and message_hashtype fields are not to be included in the hash
- Construct a string by:
- Sorting field name/value pairs including “=” separator in ascending alphabetical order
- Field name/value pairs are joined with “&” separator
- String is hashed with the shared secret using the HMAC algorithm
- message_hash value is the hex encoded HMAC output
The message_hash in a response message will use ‘%20’ instead of ‘+’ when URL-encoding values that contain spaces.
Transaction Requests¶
The following sections provide a brief description for each type of request supported by Payroc’s Hosted Payment Page solution.
See the Request Fields section for additional details regarding the functionality supported and options available.
Details for the URL to be used for each type of request are provided in the Examples section.
Card Payment Transaction¶
The merchant can specify a payment amount in the transaction request or allow the user to enter the payment amount when the page is displayed.
Sale or Pre-Authorization transactions can be processed using a hosted page. If Pre-authorization transactions are processed then one of Payroc’s other interfaces must be used to process Completion transactions.
Token Transaction¶
A Token is a unique ID that can be created and used in place of credit card information for future payment processing.
A Token transaction request can be used to create a new Token or update the card number and expiry date associated with an existing Token.
For Token creations, the Token ID value can be included in the request or generated by Payroc.
Token & Card Payment Transaction¶
A single request can be used to create or update a Token and process a payment amount by including a combination of the fields supported for Token and Card Payment requests.
User Pay Transaction¶
Should the merchant want to shift the card processing fees to the user, a User Pay model can be used. The merchant allows the user to choose a card product to complete the payment. The chosen card product is then used to calculate the fee. The rate used to calculate the fee will be shared with Payroc in the merchant’s User Pay setup.
Token & Card User Pay Transaction¶
Similar to User Pay Transaction and Token transaction. The merchant can specify that the user completes the payment using a card product selected, which will create a token, use the token to complete the transaction and optionally return the token to the merchant.
User Pay Models¶
There are 2 models a merchant can use to accept payments passing the fee onto the user. In the first model, the merchant lets the user select the card product they would like to use to complete the payment. Depending on the card product chosen, the merchant will calculate the fee the user will pay. The user is then redirected to the hosted payment pages to complete the transaction. The fee amount and card product are sent to the HPP site so that the fee can be shown to the user, with a check box to confirm the user agrees to the fee.
The second model allows the merchant to not specify the fee amount and card product, and have the HPP site show the fee amount based on the card the user decides to use. When a token is used the fee amount is calculated based on the tokens card product. If a token action is specified then the token can be created or updated.
Request Fields¶
Common Request Fields¶
Following fields are supported for Token and Card Payment transaction requests:
| Field Name | Data Definition | Description |
|---|---|---|
| terminal_id | 8 bytes, alphanumeric Mandatory |
Unique ID assigned by Payroc which identifies the merchant setup to be used for transaction processing |
| reference_number | 60 bytes alphanumeric, hyphen, forward slash(“/”) Mandatory |
Unique transaction reference number to be assigned by the merchant application |
| return_url | Variable length Mandatory |
URL where the user is to be returned after transaction processing has been completed. |
| card_type | 1 byte, alpha Optional |
Used to force the entry of a specific card type. Values:
If card_type field is not included in the request then the user can enter a card number for any of the supported card types. Not used for User Pay transactions |
| cvv | 1 byte, alpha Optional |
Specifies whether the CVV field is to be displayed on the hosted page and if the user must enter a value Values:
If cvv field is not included in the request then the default behaviour will be the same as “cvv=Y” |
| avs | 1 byte, alpha Optional |
Specifies whether the AVS field is to be displayed on the hosted page and if the user must enter a value Values:
If avs field is not included in the request then the default behaviour will be the same as “avs=Y” |
| cardholder_name | 1 byte, alpha Optional |
Specifies whether the Cardholder Name field is to be displayed on the hosted page and if the user must enter a value Values:
If cardholder_name field is not included in the request then the default behaviour will be the same as “cardholder_name=N” |
| echo | 256 bytes alphanumeric, lower case letters, hyphen, forward slash(“/”) Optional |
Optional field that can be used to pass a value in the request which is to be returned in the response |
| locale | 5 bytes Optional |
Specifies the language to be used for the hosted page display. Values:
If the locale field is not included in the request then the page will be displayed with English text. |
| message_text | 256 UTF-8 characters Optional |
Optional field which can be used to display a text message on the hosted page |
| resend | 3 bytes, alpha Optional |
If “resend=yes” is included in the request and the transaction was already processed then the original result will be returned in the response. terminal_id and reference_number will be used to match the request with a previous request. |
| message_hash | 32 bytes numeric, A-F Optional |
SHA256 hash will be used to verify the source and integrity of a message. Hosted page must be configured by Payroc support in order to use this option. See Message Hashing section for additional details. |
| massage_hashtype | 6 bytes, alpha Mandatory, if message_hash is used. |
The hash type used to create the message_hash field. Values:
SHA256 is currently the only supported hash type. |
Card Payment Request Fields¶
Following fields are supported for Card Payment requests:
| Field Name | Data Definition | Description |
|---|---|---|
| tran_type | 1 byte, alpha Mandatory |
Specifies the type of transaction that is to be processed by the hosted page. Values:
If Pre-authorization transactions are processed then one of Payroc’s other interfaces must be used to process Completion transactions. Not used for User Pay transactions. All User Pay transactions are pre-auth only. |
| amount | 10 bytes, numeric Mandatory, if fixed_amount is Y Optional if fixed_amount is N |
The transaction amount for the transaction with no currency signs or decimal. Example: Value of “100” would be used for $1.00 |
| fixed_amount | 1 byte, alpha Optional |
Specifies whether the user can modify the amount field on the hosted page. Values:
If fixed_amount field is not included in the request then the user cannot change the amount. Not used for User Pay transactions. |
| token | 30 bytes alphanumeric plus symbols: A-Z 0-9 : @ | - + / _ ,
Optional |
A unique ID that can be used in place of a credit card for payment processing. The card information stored for the Token is displayed on the page for verification by the user. |
Token Request Fields¶
Following fields are supported for Token transaction requests:
| Field Name | Data Definition | Description |
|---|---|---|
| token | 30 bytes alphanumeric plus symbols: A-Z 0-9 : @ | - + / _ ,
Mandatory |
A unique ID that can be created and used in place of a credit card for future payment processing. The token ID value can be specified by the merchant and/or automatically generated by Payroc. Submitting a TOKEN value containing a “?” specifies that the token ID value is to be generated by Payroc. Token IDs will be generated by Payroc based on configuration fields chosen by the merchant. |
| token_action | 10 bytes, alpha Mandatory |
Values: “ADD” - Used to add/create the token “UPDATE” - Used to modify card number, expiry, date or reference data associated with a token |
| token_reference_number | 30 bytes alphanumeric plus symbols: A-Z a-z 0-9 - / \
Optional |
Used to submit optional reference data to be captured with a Token. |
| open_card | 1 byte, alpha Optional |
Specifies whether a card number can be changed for Token Update requests Values:
If open_card field is not included with the request then default behaviour will be the same as “open_card=Y” |
User Pay Request Fields¶
Following fields are supported for (Token) User Pay transaction requests:
| Field Name | Data Definition | Description |
|---|---|---|
| token | 30 bytes alphanumeric plus symbols: A-Z 0-9 : @ | - + / _ ,
Optional |
A unique ID that can be used in place of a credit card for payment processing. The card information stored for the Token is displayed on the page for verification by the user. For userpay, the token is used instead of a pan For tokenuserpay, the merchant can specify that a token must be created or updated and that token result be used in transaction. |
| fee_amount | 8 bytes, numeric required if card_product is specified |
The fee amount calculated based on the requested card type/product and payment amount. |
| card_product | 2 bytes, alpha required if fee_amount is specified |
Specifies card product the user selected on merchant site Values:
|
| open_card | 1 byte, alpha Optional |
Specifies whether a card number can be changed for Token Update requests Values:
If open_card field is not included with the request then default behaviour will be the same as “open_card=Y” |
Response Fields¶
Fields listed in the table provided below can be included in a Hosted Payment Page response.
Mandatory indicates that the field is always included in responses. Optional fields may be returned depending on the type of request and the transaction processing results.
| Field Name | Data Definition | Description |
|---|---|---|
| auth_result | 1 byte, alpha Mandatory |
Values:
|
| result_text | 20 bytes, alphanumeric Mandatory |
Provides text describing the transaction result |
| terminal_id | 8 bytes, alphanumeric Mandatory |
Returns the Terminal ID value specified in the request |
| reference_number | 60 bytes alphanumeric, hyphen, forward slash(“/”) Mandatory |
Unique transaction reference number included in the request |
| card_type | 1 byte, alpha Optional |
Specifies the card type if a valid card number was entered on the hosted page card_type is not returned for User Pay transactions |
| cardholder_name | 40 bytes, alpha plus space, hyphen, period Optional |
Cardholder name entered on the hosted page will be returned if valid data was input by the user |
| echo | 256 bytes alphanumeric, lower case letters, hyphen, forward slash(“/”) Optional |
Echo value will be returned if the field was included in the request |
| card_mask | 20 bytes, numeric, asterisks Optional |
Masked card number will be returned if valid data was input by the user |
| expiry_date | 4 bytes, numeric Optional |
Expiry date in MMYY format will be returned if a value was entered by the user |
| token | 30 bytes alphanumeric plus symbols: A-Z 0-9 : @ | - + / _ ,
Optional |
Token value specified in the request or value generated by Payroc will be returned |
| token_action | 10 bytes, alpha Optional |
Token action specified in the request will be returned |
| message_hash | 32 bytes 0-9 A-F
Mandatory, if request included message_hash |
SHA256 hash to be used to verify the source and integrity of the response message. |
| massage_hashtype | 6 bytes, alpha Mandatory, if message_hash is used. |
The hash type used to create the message_hash field. Values:
|
Examples¶
Card Payment¶
The URL for Card Payments requests must include “/v3/pay” as shown in the example provided below.
Request processed for this example is a sale transaction with default values used for optional request fields:
https://merchantsite.poweredbycaledoncard.com/v3/pay?terminal_id=TESTTERM
&tran_type=S&reference_number=PAY1&return_url=https://result.merchantsite.com/&amount=100
The hosted page displayed for this request is shown on the next page:
- CVV and AVS fields are not included in the request so the CVV & AVS input fields are included on the page as required fields.
- The amount field is displayed with a gray background, as the user cannot change the value.
Example of the response returned if the card payment transaction is approved:
https://result.merchantsite.com/?terminal_id=TESTTERM&auth_result=A
&card_mask=************1111&expiry_date=0116&amount=100&tran_type=S
&reference_number=PAY1&card_type=M&result_text=T76734 $1.00
Example of the response returned if the user cancels the card payment transaction:
https://result.merchantsite.com/?auth_result=C&terminal_id=TESTTERM&reference_number=PAY1
Sample Page - Card Payment using default values
Token Transactions¶
The URL for Token requests must include “/v3/token” as shown in the examples provided below.
Token Creation
Request processed for this example is a token transaction with no CVV or AVS authentication. token_action has a value of “ADD” to specify that a new Token is to be created using the card information captured by the hosted page.
https://merchantsite.poweredbycaledoncard.com/v3/token?token_action=ADD&token=TESTTOKEN5
&reference_number=TOKEN1&terminal_id=TESTTERM&return_url=https://result.merchantsite.com/
&cvv=N&avs=N
The hosted page displayed for this request is shown on the next page.
Example of the response returned if the token transaction is successful:
https://result.merchantsite.com/?auth_result=A&result_text=TOKEN ADDED&token_action=ADD
&token=TESTTOKEN5&reference_number=TOKEN1&terminal_id=TESTTERM&card_type=V
&card_mask=***********1234&expiry_date=0615
Example of the response returned if the user cancels the token transaction:
https://result.merchantsite.com/?auth_result=C&terminal_id=TESTTERM&reference_number=TOKEN1
Sample page - Token Creation with no CVV or AVS authentication
Token Update
Request processed for this example is a token transaction where the card information for an existing Token is to be updated. token_action has a value of “UPDATE” to specify that the card information captured by the hosted page is to be used to update the Token specified in the request.
https://merchantsite.poweredbycaledoncard.com/v3/token?token_action=UPDATE&token=TESTTOKEN5
&reference_number=TOKEN2&terminal_id=TESTTERM&return_url=https://result.merchantsite.com/
&cvv=N&avs=N
The hosted page displayed for this request is shown on the next page. The current card information stored for the Token is displayed on the page which can be changed by the user.
Example of the response returned if the token transaction is successful:
https://result.merchantsite.com/?auth_result=A&result_text=TOKEN UPDATED&token_action=UPDATE
&token=TESTTOKEN5&reference_number=TOKEN2&terminal_id=TESTTERM&card_type=M
&card_mask\************6789&expiry_date=1215
Example of the response returned if the user cancels the token transaction:
https://result.merchantsite.com/?auth_result=C&terminal_id=TESTTERM
&reference_number=TOKEN2
Sample page - Token Update with no CVV or AVS authentication
Token & Card Payment¶
The URL for Token & Card Payment requests must include “/v3/tokenpay” as shown in the example provided below.
Request processed for this example is a token and card payment transaction using a single request:
https://merchantsite.poweredbycaledoncard.com/v3/tokenpay?terminal_id=TESTTERM&tran_type=S
&reference_number=TOKENPAYMENT&return_url=https://result.merchantsite.com/&amount=100
&token_action=ADD&token=TESTTOKEN
The hosted page displayed for this request is shown on the next page. The page appears to be the same as the Card Payment sample page to the user as the Token Creation is handled in the background.
Example of the response returned if the token transaction is successful and the payment amount is approved:
https://result.merchantsite.com/?reference_number=TOKENPAYMENT&token=TESTTOKEN
&terminal_id=TESTTERM&expiry_date=0216&result_text=T59662 $1.00&auth_result=A
&tran_type=S&amount=100&card_type=M&card_mask=************1111
Example of the response returned if the user cancels the transaction:
https://result.merchantsite.com/?auth_result=C&terminal_id=TESTTERM
&reference_number=TOKENPAYMENT
Sample Page - Token & Card Payment
Card User Pay Payment¶
Example of User Pay with fee accept checkbox:
https://merchantsite.poweredbycaledoncard.com/v3/userpay?terminal_id=TESTTERM&
reference_number=TESTUSERPAYREF&return_url=https://result.merchantsite.com/&
amount=10000&avs=N&cvv=N&fee_amount=279&card_product=VC
Example response:
https://result.merchantsite.com/?amount=10000&auth_result=A&
card_mask=************1135&card_type=VISA&expiry_date=0923&
fee_amount=279&reference_number=TESTUSERPAYREF&
result_text=success&terminal_id=TESTTERM&total_amount=10279
Sample Page - Card User Pay Payment
Token & Card User Pay Payment¶
Example requests:
ADD with token TESTTOKEN
https://merchantsite.poweredbycaledoncard.com/v3/tokenuserpay?terminal_id=TESTTERM&
reference_number=TESTTERM000002&return_url=https://result.merchantsite.com/&
amount=1000&tran_type=S&avs=N&cvv=N&fee_amount=25&card_product=VC&
token=TESTTOKEN&token_action=ADD
ADD with token ?
https://merchantsite.poweredbycaledoncard.com/v3/tokenuserpay?terminal_id=TESTTERM&
reference_number=TESTTERM000002&return_url=https://result.merchantsite.com/&
amount=1000&tran_type=S&avs=N&cvv=N&fee_amount=25&card_product=VC&
token=?&token_action=ADD
UPDATE token TESTTOKEN
https://merchantsite.poweredbycaledoncard.com/v3/tokenuserpay?terminal_id=TESTTERM&
reference_number=TESTTERM000002&return_url=https://result.merchantsite.com&
amount=1000&tran_type=S&avs=N&cvv=N&fee_amount=25&card_product=VC&
token=TESTTOKEN&token_action=UPDATE
Example response:
https://result.merchantsite.com/?amount=10000&auth_result=A&
card_mask=************1135&card_type=VISA&expiry_date=0923&
fee_amount=279&reference_number=TESTTOKENUSERPAYREF&
result_text=success&terminal_id=TESTTERM&total_amount=10279
Card Payment Request with Message Hash¶
Steps required to create message hash provided below are based on following example of Sale transaction:
https://test.poweredbycaledoncard.com/v3/pay?terminal_id=HPPTEST1
&reference_number=ABC07TEST&return_url=https://caledontest.poweredbycaledoncard.com/testing
&amount=150&tran_type=S&cvv=N&avs=N
Following message hash secret key is used for example:
26d8df69e5f603b094c8d2f09490f86f
Only the request data fields and values are to be used for message hash creation:
terminal_id=HPPTEST1&reference_number=ABC07TEST&
return_url=https://caledontest.poweredbycaledoncard.com/testing
&amount=150&tran_type=S&cvv=N&avs=N
Any request fields with no value must be excluded.
The field names and values must be URL-encoded and sorted before message hash creation:
amount=150&avs=N&cvv=N&reference_number=ABC07TEST
&return_url=https%3A%2F%2Fcaledontest.poweredbycaledoncard.com%2Ftesting
&terminal_id=HPPTEST1&tran_type=S
Example of the request above with message hash generated:
https://test.poweredbycaledoncard.com/v3/pay?amount=150&avs=N&cvv=N&reference_number=ABC07TEST
&return_url=https%3A%2F%2Fcaledontest.poweredbycaledoncard.com%2Ftesting
&terminal_id=HPPTEST1&tran_type=S&message_hashtype=SHA256
&message_hash=892542c4a0cdb714cc1ba6439438db28fae2d2e92eaf38eceb728fde433e2ca7
The field names and values are URL-encoded, field name/value pairs are sorted, and the message_hashtype and message_hash fields must be included.