Not logged in
Log In Now
This documentation provides the details necessary to utilize a hosted payment form to collect payment information from your customers. This is the fastest and easiest way to get your website or application integrated and ready to collect payments from your customers without any need to directly see or access the credit card information being provided. A hosted payment form can be tailored to fit the look and feel of your existing site or application while mitigating your site's risk of PCI liability by diverting the entire payment collection process through the SwervePay system.
Please use the following links to quickly navigate this documentation.
The hosted payment form is designed to provide a simple drop-in module for payment collection in any web-facing site or application.
The process for providing this integration works like this: A customer utilizing the existing site or application is redirected via an HTTP POST request to the designated SwervePay payment form URL. This POST request securely passes all information regarding the transaction with it and leaves the task of collecting cardholder data and processing the transaction to SwervePay. Following the completion of the transaction the customer is automatically redirected back to a specified finish URL via an HTTP GET request. Requests in both directions utilize a basic one-way hashing algorithm utilizing a private form key to prevent any possibility of tampering.
The advantages of utilizing a hosted payment form include the complete removal of any direct liability pertaining to access or visibility of cardholder data available to your system, even momentarily. All communication of payment-related data and transaction processing happens solely between the customer's own local browser and the SwervePay system.
Return to the topThe process for utilizing the payment form requires minimal integration effort. Examples of form requests can be found in the Examples at the end of this document.
A triggering event in your site or application creates the need to process a payment.
Preparation to redirect the customer to the SwervePay hosted payment form is made by determining the pertinent information necessary to process the transaction including the transaction amount, customer identification (if applicable), and any additional custom field data or other tracking information deemed necessary. A private form key is then concatenated with this data and the resulting string is one-way hashed to form the signature to ensure data integrity through the process.
The customer is routed to the hosted payment form URL via an HTTP POST. This is typically done via a form submission from your own site or application. The private form key is again concatenated with the specified parameter data to validate the integrity of parameter data.
The customer interacts with the hosted payment to provide payment data (optionally leveraging any prior payment options used in the past, if the SwervePay customer module is utilized) and completes or cancels the transaction.
Following the completion of the transaction all parameter data is once again hashed with the private form key and the customer's browser is redirected via an HTTP GET request back to a specified finish URL (utilizing an HTTP 302 redirect). The response data is validated by your site or application using the hashed signature.
At present, configuration of v2.1 payment form(s) is accomplished through a collaborative process with your SwervePay account representative. If you need any assistance, please do not hesitate to contact support at support@swervepay.com.
Return to the topIn order to fully isolate your external site or system from the payment process, the customer's interactions with the payment form exist directly between their browser and the SwervePay hosted payment form. As such, it is vital that sensitive data about the transaction be protected in such a way as to prevent the customer (or any other "man-in-the-middle") from being able to tamper with it.
To solve this dilemma, a private form key is generated for each hosted payment form and is known only to your site or application and to SwervePay. This key is then used in the generation of each payment request to ensure that the important payment details (amount of the transaction, product information, etc.) is properly transmitted to and from the payment form with no possibility of tampering.
The process for utilizing this private form key to secure your payment form data involves utilizing a cryptographic hash function to produce a one-way hash of the set of concatenated parameter data, prepended with your private form key, such that the resulting digest is provided as a signature of the data transmitted. Upon receiving data, the payment form follows the same procedure to generate the string of parameter data from the values actually passed, prepended by the private form key, and hashing this string with the same cryptographic hash function to compare the digest signature with the one that was passed. If these hash signatures do not match, the payment form will be aware that tampering has taken place and will automatically abort the payment process.
It is equally important that the data returned from the payment form to your site or application is also protected from tampering. As such, the same process as was used to secure the inbound data is applied on the outbound data. In this case all parameter data will be included in the list of field data to be hashed (as all outbound payment result data is static and should not be modified by a customer) and the resulting hash signature will allow the site or application receiving the response data to verify the integrity of the data in its entirety.
Given the listed parameters below, the hash parameter will be determined by concatenating the Private Form Key with the values corresponding to the field names identified in the hashFields parameter.
Example Private Form Key = 6bda3568016f9f2d4113f2dbaa56e0bc
Example Form SID = 89f6f1d895d1aa5e296076c5f113b4dc
transactionAmount = 10.00
ext_productUuid = 084F0DC0-F813-4E4D-BCD8-862200BFE7AC
hashFields = "transactionAmount ext_deviceUuid"
To compute the hash in question, the values for the fields in the hashFields parameter were concatenated with the Private Form Key value:
6bda3568016f9f2d4113f2dbaa56e0bc10.00084F0DC0-F813-4E4D-BCD8-862200BFE7AC$ echo -n "6bda3568016f9f2d4113f2dbaa56e0bc10.00084F0DC0-F813-4E4D-BCD8-862200BFE7AC" | md5sum
f510968e800d5390017a1424f838de86 -Example form HTML:
<form action="https://secure.swervepay.com/form/89f6f1d895d1aa5e296076c5f113b4dc/index.html" method="POST">
<input type="hidden" name="transactionAmount" value="10.00" />
<input type="hidden" name="ext_productUuid" value="084F0DC0-F813-4E4D-BCD8-862200BFE7AC" />
<input type="hidden" name="hash" value="f510968e800d5390017a1424f838de86" />
<input type="hidden" name="hashFields" value="transactionAmount ext_deviceUuid" />
<input type="submit" name="submit" value="Pay Now!" />
</form>
Each hosted payment form has a unique form SID. This SID is used to determine the URL that can be used to access the form. The HTTP POST made from your site or application should be sent to this URL. The format for the URL is the following:
https://secure.swervepay.com/form/{formSID}/index.htmlExample:
form SID = 89f6f1d895d1aa5e296076c5f113b4dc
URL = https://secure.swervepay.com/form/89f6f1d895d1aa5e296076c5f113b4dc/index.html
These parameters are used to validate the integrity of the data passed. See Securing a Payment Form for more information.
| Parameter | Required | Description |
|---|---|---|
| hash | Required | The computed hash used to verify data integrity. This field is calculated by concatenating the private form key with the values of the space-separated fields dictated in the hashFields parameter. |
| hashFields | Required | A space-separated list of field names whose values are to be included in the string
that will be hashed using the designated hash function.
IMPORTANT: The order of the fields listed here is important! When hashing, the private form key will be prepended to the values from the parameters in the order they appear in this space-separated list. See Securing a Payment Form for more information. |
| hashFunction | The hash function to be used. The default value if left unspecified is "md5". Response
data will always contain this parameter and the hash function used in the response will always be the
same function used for the request.
Valid Values: "md5", "sha1", "sha256", "sha512" |
These parameters define control of the payment form.
| Parameter | Required | Description |
|---|---|---|
| finishUrl | If provided, this will dictate the return URL the customer is routed to after leaving the SwervePay hosted payment form. If this parameter is not provided the customer will be routed to the default finishUrl for the payment form. |
Payment-related data.
| Parameter | Required | Required Hash Field | Max Length | Description |
|---|---|---|---|---|
| description | This is an optional brief description passed into the payment form. This description describes the service or item being purchased and will be visible to the customer at the top of the payment form. | |||
| transactionAmount | Required | Required | 12 | The amount of the transaction to process. This should be a positive numeric value and should not contain a dollar sign or any additional symbols (e.g. "10.00"). |
Customer-related data. These fields are only necessary if utilizing the SwervePay customer module. When creating a new SwervePay customer this will be used to populate the customer record. Future access for this customer will only need the usage of the customerId parameter unless other field data updates are needed.
| Parameter | Required | Required Hash Field | Max Length | Description |
|---|---|---|---|---|
| accountRefId | 256 | Account Number from the calling system | ||
| action_addCustomer | 1 | Indication to add a new customer with this payment.
Note that a customer will be created on a completed transaction
regardless of success or failure of the payment. Future
transactions for this customer should utilize the returned
customerId parameter. If passed, this parameter should always be sent with a value of "1". action_addCustomer and customerId are mutually exclusive and should not be passed with the same request. |
||
| action_loadBillingFromCustomer | 1 | Indication to utilize the customer demographic data
provided to populate the respective billing demographic fields.
To function as intended, this field requires that a customerId
parameter (referring to an existing customer record) be passed as well.
If passed, this parameter should always be sent with a value of "1". |
||
| action_loadCustomerFromBilling | 1 | Indication to utilize the billing demographic data
provided to populate the respective customer demographic fields.
This parameter is passed in lieu of any customer*
parameter data. This can be passed with the creation of a new customer or on
future customer payments to update the customer record from the billing data.
If passed, this parameter should always be sent with a value of "1". |
||
| customerAddress1 | 255 | Customer Address Line 1 | ||
| customerAddress2 | 255 | Customer Address Line 2 | ||
| customerCity | 255 | Customer City | ||
| customerCompany | 255 | Customer Company | ||
| customerEmail | 255 | Customer Email | ||
| customerFaxNumber | 14 | Customer Fax Number | ||
| customerFirstName | Conditional | 255 | Customer First Name This field is required when action_addCustomer parameter is passed. |
|
| customerId | Conditional | 1 | 12 | Customer Id This field is required whenever an existing customer record is being used. Providing this parameter will allow a customer to utilize previously used payment options from the payment form, avoiding the need to re-enter data again. This field cannot be passed in conjunction with action_addCustomer. If this parameter is passed it is required to be included in the provided hashFields. |
| customerLastName | Conditional | 255 | Customer Last Name This field is required when action_addCustomer parameter is passed. |
|
| customerPhoneNumber | 14 | Customer Mobile Number | ||
| customerRefId | 256 | Customer Reference Id from the calling system | ||
| customerSecondaryNumber | 14 | Customer Secondary Number | ||
| customerState | 2 | Customer 2-letter state abbreviation | ||
| customerZip | 10 | Customer ZIP code | ||
| systemCustomerRefId | 256 | System Customer Reference Id from the calling system |
In addition to the parameters listed here, any additional parameters can be passed into the payment form as well (and utilized and hashed via the hashFields like any other parameter). This parameter data will be unused within the payment form but will be returned to the finishURL. Typically these fields are used for internal tracking for your site or application.
To avoid parameter name collisions with protected keywords for SwervePay parameters, it is suggested you namespace your own parameters in some manner (e.g. EXT_productUuid or CompanyName_trackingCode).
Return to the topThese parameters are used to validate the integrity of the data passed. See Securing a Payment Form for more information.
| Parameter | Description |
|---|---|
| hash | The computed hash used to verify data integrity. This field is calculated by concatenating the private form key with the values of the space-separated fields dictated in the hashFields parameter. |
| hashFields | A space-separated list of field names whose values are to be included in the string
that will be hashed using the designated hash function.
IMPORTANT: The order of the fields listed here is important! When hashing, the private form key will be prepended to the values from the parameters in the order they appear in this space-separated list. See Securing a Payment Form for more information. |
| hashFunction | The hash function to be used. The default value if left unspecified is "md5". Response
data will always contain this parameter and the hash function used in the response will always be the
same function used for the request.
Valid Values: "md5", "sha1", "sha256", "sha512" |
These parameters define control of the payment form.
| Parameter | Description |
|---|---|
| callStatus | This parameter dictates the status of the call to the payment form.
"1" => The customer successfully navigated the payment form and returned via the successful completion or cancellation of a transaction. "0" => An error or other issue occurred and the user was forcefully redirected to the return URL. In this case the error parameter(s) for additional information. Likely causes include tampering with parameter data for fields included in the provided hashFields. While this should indicate that no transaction was processed, the calling site or application should still check for the existence of a transactionStatus parameter to be safe. |
| error | If there is any issue or error with the interaction between the
customer and the payment form, they will be redirected back to the finishUrl
with one more more error parameters. These will be human-readable
messages describing the issue. If a callStatus other than "1" is returned these fields should be checked for more information. |
Payment-related data.
| Parameter | Description |
|---|---|
| authCode | Authorization Code |
| avsResult | AVS Result |
| billAddress1 | Address Line 1 |
| billAddress2 | Address Line 2 |
| billCity | City |
| billCompany | Company |
| billEmail | |
| billFaxNumber | Fax Number |
| billFirstName | First Name |
| billLastName | Last Name |
| billPhoneNumber | Mobile Number |
| billSecondaryNumber | Secondary Number |
| billState | 2-letter state abbreviation |
| billZip | ZIP code |
| cvvResult | CVV Result |
| description | This is an optional brief description passed into the payment form. This description describes the service or item being purchased and will be visible to the customer at the top of the payment form. |
| responseCode | Numeric mapping of processor response. See Appendix C in the REST API documentation for additional detail. |
| responseMessage | Human readable response message |
| transactionAmount | The amount of the transaction to process. This should be a positive numeric value and should not contain a dollar sign or any additional symbols (e.g. "10.00"). |
| transactionId | Transaction unique identifier |
| transactionStatus | This parameter indicates the status of the transaction processing attempt.
"1" => The payment was processed successfully. "0" => The payment failed or was declined. In this case the human-readable responseMessage should be presented for further clarification. This message, along with the numeric responseCode, may be needed to assist in troubleshooting the decline with the issuing bank. |
Customer-related data. These fields are only returned if utilizing the SwervePay customer module and a customer transaction has been processed (meaning either customerId or action_addCustomer were provided with the request).
| Parameter | Description |
|---|---|
| accountRefId | Account Number from the calling system |
| customerAddress1 | Customer Address Line 1 |
| customerAddress2 | Customer Address Line 2 |
| customerCity | Customer City |
| customerCompany | Customer Company |
| customerEmail | Customer Email |
| customerFaxNumber | Customer Fax Number |
| customerFirstName | Customer First Name |
| customerId | Customer Id This field will be needed for subsequent transactions for this customer. |
| customerLastName | Customer Last Name |
| customerPhoneNumber | Customer Mobile Number |
| customerRefId | Customer Reference Id from the calling system |
| customerSecondaryNumber | Customer Secondary Number |
| customerState | Customer 2-letter state abbreviation |
| customerZip | Customer ZIP code |
| systemCustomerRefId | System Customer Reference Id from the calling system |
In addition to the parameters listed here, any additional parameters passed in with the request form will be hashed and passed to the finishURL as well.
Return to the topExample Private Form Key = 6bda3568016f9f2d4113f2dbaa56e0bc
Example Form SID = 89f6f1d895d1aa5e296076c5f113b4dc
<form action="https://secure.swervepay.com/form/89f6f1d895d1aa5e296076c5f113b4dc/index.html" method="POST">
<input type="hidden" name="description" value="A new widget" />
<input type="hidden" name="transactionAmount" value="10.00" />
<input type="hidden" name="ext_productUuid" value="084F0DC0-F813-4E4D-BCD8-862200BFE7AC" />
<input type="hidden" name="hashFields" value="transactionAmount ext_productUuid" />
<input type="hidden" name="hash" value="f510968e800d5390017a1424f838de86" />
<input type="submit" name="submit" value="Pay Now" />
</form>
<form action="https://secure.swervepay.com/form/89f6f1d895d1aa5e296076c5f113b4dc/index.html" method="POST">
<input type="hidden" name="description" value="A new widget" />
<input type="hidden" name="action_addCustomer" value="1" />
<input type="hidden" name="action_loadCustomerFromBilling" value="1" />
<input type="hidden" name="transactionAmount" value="25.00" />
<input type="hidden" name="ext_productUuid" value="084F0DC0-F813-4E4D-BCD8-862200BFE7AC" />
<input type="hidden" name="hashFields" value="action_addCustomer action_loadCustomerFromBilling
transactionAmount ext_productUuid" />
<input type="hidden" name="hash" value="41b1960fff7bc2994e844959a80c6df9" />
<input type="submit" name="submit" value="Pay Now" />
</form>
<form action="https://secure.swervepay.com/form/89f6f1d895d1aa5e296076c5f113b4dc/index.html" method="POST">
<input type="hidden" name="description" value="A new widget" />
<input type="hidden" name="customerId" value="200000000001" />
<input type="hidden" name="transactionAmount" value="15.00" />
<input type="hidden" name="ext_productUuid" value="084F0DC0-F813-4E4D-BCD8-862200BFE7AC" />
<input type="hidden" name="hashFields" value="customerId transactionAmount ext_productUuid" />
<input type="hidden" name="hash" value="875fb789d7b1b03cdf634f1584509f46" />
<input type="submit" name="submit" value="Pay Now" />
</form>