View the Project on GitHub PineapplePayments/pineapple-developer-center
Follow this guide to begin using Transax to collect payments in your application when a physical credit or debit card is not directly involved. The user experience involves either the cardholder (via the internet) or the merchant employee (accpeting credit cards over the phone) keying credit card information into a form to process a payment.
The Transax solution for these types of payments is a Hosted Payment Page. A Hosted Payment Page is a webform created and hosted on Transax servers and incorporated into your application through iFrames or redirects. This approach keeps all cardholder data on Transax servers. While the ROX Transaction API can be used in a similar scenario but without involving a page hosted on Transax servers, doing so is not considered a best practice because your application would be subject to additional PCI compliance scope.
After following this guide, your application will be able to accept basic payments on a Hosted Payment Page. The Hosted Payment Page has many additional, optional features descried in the API Reference and/or configured via the Transax portal under the Modules > Hosted Payment pages option. These additional features include the:
The API authenticates with a username and password in the API body. The example below uses a generic test account that you can use for integration purposes. If you need specific integration credentials for your use case, please contact your sales agent.
When you are ready to go live, replace the GatewayUserName and GatewayPassword with your API user’s credentials. We recommend creating a user specifically for API usage by logging into the Transax portal with your administrator credentials and accessing Settings > Manage Users.
First, using Postman or any other method at your disposal, create an internet accessible endpoint that Transax can return a webhook to with transaction results. This endpoint will be called with a form post payload - the details of which will be covered in Handling Transaction Results. We recommend that your application generate a unique URL for every Hosted Payment Page and take other appropriate measures to mitigate the risk of publically exposing a callback URL.
To create a Hosted Payment Page, substitute the endpoint you created above in the retURL parameter and the intended transaction amount in the Amount parameter. Then then send this POST request from your server:
curl --location --request POST 'https://secure.gwintegration.com/WebAPI/hppweb.aspx/ReturnHostedPaymentSetup' \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"GatewayUserName": "transaxdemo",
"GatewayPassword": "Pineapple123!",
"Amount": "1.01",
"SingleUse": "true",
"retURL": "https://postmanURLMock.com"
}
}'
NOTE: In an effort to deter malicious actors, all returnURLs are reviewed internally prior to becoming active. Users of this page will see our standard receipt upon the completion of a transaction until the approval is in place. Inquiries regarding approval status should be submitted to transax@pineapplepayments.com.
The response to this request will be a JSON object with a single key value pair, which is referred to as the Hosted Payment Page hash value.
{ "d": "Bl1aWERlBzNXZOUiqnvGuJxUaGgNyYeOq3juCRQwf%2BE%3D" }
In this example, this hash value will remain valid until it is used since "SingleUse" : "true" was set in the request. Other parameters can change the availability time or number of usage opportuniities of this page - see the API Reference for details.
The hash value used above makes up part of the URL of the hosted payment page, which should be included into your application using one of the options detailed below.
When in Integration mode (which the above API credentials leverage), you can process a successful transaction by using test credit card number 4111 1111 1111 1111 and any future expiration date. When using the above example, only those two fields will be required - see the section on other use cases or the API Reference for details on how to change required fields. Any Amount greater than $1.00 will be approved; any Amount less than $1.00 will be declined.
Certain features of the Hosted Payment Page can only be configured through the Transax portal, such as which card brands can be accepted, the cash discount fee rates and language, and the logos that appear. Contact your sales agent if you need further assistance.
Upon receiving the Hosted Payment Page hash value from the previous step, redirect the user to a page or new window at the following URL, substituting the hash value received from the API response: https://secure.transaxgateway.com/HostedPaymentForm/HostedPaymentPage.aspx?hash=[INSERT HOSTED PAYMENT PAGE HASH VALUE HERE]
On this page, your customer can complete the payment.
Upon receiving the Hosted Payment Page hash value from the previous step, embed an iFrame in your page using the hash value received from the API response.
<iframe id='hpp_iframe' src='https://secure.transaxgateway.com/HostedPaymentForm/HostedPaymentPage.aspx?hash=[INSERT HOSTED PAYMENT PAGE HASH VALUE HERE]'></iframe>
Once your customer passes all page validations and selects the Submit Order button, the page will redirect to the URL that was set in the RetURL parameter of the API call (if RetURL was not set the customer will be taken to a generic confirmation page). This will occur regardless of transaction results (i.e. same experience for Approval and Decline).
At the time of this redirect, the RetURL webhook will be sent a form post that is formatted as follows. We recommend that your application display a confirmation page to the user and handle failure cases based on the content of the form post. A statuscode = 1 indicates a success, any other value is a failure.
curl --location --request POST '' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'authcode=9999' \
--data-urlencode 'avsmsg=' \
--data-urlencode 'transid=' \
--data-urlencode 'authmsg=Approved' \
--data-urlencode 'statuscode=1' \
--data-urlencode 'avscode=' \
--data-urlencode 'cvv2code=' \
--data-urlencode 'cvv2msg=' \
--data-urlencode 'safeid=' \
--data-urlencode 'statusmsg=Approved' \
--data-urlencode 'orderid=' \
--data-urlencode 'expdate=07/23' \
--data-urlencode 'last4=4*****1111' \
--data-urlencode 'cardtype=Visa'
Now that you are able to successfully process a transaction, you can further configure the Hosted Payment Page for your specific use case. The below examples cover some common use cases; the API Reference contains the full set of options.
You want to optimize your payments flow to eliminate data entry and reduce the risk of customer abandonment. The Hosted Payment Page fields can be pre-populated with data stored or entered elsewhere in your application.
In this example, we will pre-populate some key data fields like customer name and address. All the customer will need to do is enter their payment information on the Hosted Payment Page.
curl --location --request POST 'https://secure.gwintegration.com/WebAPI/hppweb.aspx/ReturnHostedPaymentSetup' \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"GatewayUserName": "TransaxDemo",
"GatewayPassword": "Pineapple123!",
"SinglueUse": "true",
"Amount": "1.01",
"FirstName": "Suzie",
"LastName": "Customer",
"Address1": "444 Central Avenue",
"Address2": "Unit B",
"City": "Centrallia",
"State": "PA",
"Zip": "15999",
"Country": "United States"
}
}'
Using the API, you can show, hide, require, or lock fields as needed to collect the data appropriate for your use case.
In this example, the bare minimum of fields we recommend you use for most cases are included and marked required for the cardholder to fill out. Additioinally, one of the Transax custom fields is included and pre-populated using the API, but locked to prevent users from changing the value.
curl --location --request POST 'https://secure.gwintegration.com/WebAPI/hppweb.aspx/ReturnHostedPaymentSetup' \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"GatewayUserName": "TransaxDemo",
"GatewayPassword": "Pineapple123!",
"Amount": "1.01",
"SingleUse": "true",
"FirstName_Required": "true",
"FirstName_Visible": "true",
"LastName_Required": "true",
"LastName_Visible": "true",
"Address1_Required": "true",
"Address1_Visible": "true",
"Address2_Required": "false",
"Address2_Visible": "true",
"City_Required": "true",
"City_Visible": "true",
"State_Required": "true",
"State_Visible": "true",
"Zip_Required": "true",
"Zip_Visible": "true",
"Country_Required": "true",
"Country_Visible": "true",
"Custom_Field_1": "Order-12345",
"Custom_Field_1_Required": "true",
"Custom_Field_1_Visible": "true",
"Custom_Field_1_Disabled": "true",
"Company_Visible": "false",
"Phone_Visible": "false",
"Fax_Visible": "false",
"EMail_Visible": "false",
"Website_Visible": "false",
"Tax_Visible": "false",
"Shipping_Visible": "false",
"OrderID_Visible": "false",
"PONumber_Visible": "false",
"InvoiceID_Visible": "false",
"ShippingFirstName_Visible": "false",
"ShippingLastName_Visible": "false",
"ShippingCompany_Visible": "false",
"ShippingAddress1_Visible": "false",
"ShippingAddress2_Visible": "false",
"ShippingCity_Visible": "false",
"ShippingState_Visible": "false",
"ShippingZip_Visible": "false",
"ShippingCountry_Visible": "false",
"ShippingEmail_Visible": "false",
"ShippingPhone_Visible": "false",
"ShippingFax_Visible": "false",
"ShippingTrackingNumber_Visible": "false",
"ShippingCarrier_Visible": "false"
}
}'
Your application can use the Hosted Payment Page to verify and tokenize a credit card, then receive a SAFE ID. That SAFE ID can then be used with the ROX Transaction API to conduct secure transactions without your application interacting with credit card data. This approach can be useful when your user experience collects card data and runs transactions at separate steps, or when conducting recurring type billing.
In this example, a customer will see only a card number and expiration date field. This information will be verified to be a real card, tokenized, and stored in the Transax SAFE. The data passed to the RetURL will contain a safeid which can then be used with the Transax ROX Transaction API.
curl --location --request POST 'https://secure.gwintegration.com/WebAPI/hppweb.aspx/ReturnHostedPaymentSetup' \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"GatewayUserName": "TransaxDemo",
"GatewayPassword": "Pineapple123!",
"Amount": "0",
"SingleUse": "true",
"AutoSAFE": "1",
"retURL": "https://postmanURLMock.com",
"FirstName_Visible": "false",
"LastName_Visible": "false",
"Address1_Visible": "false",
"Address2_Visible": "false",
"City_Visible": "false",
"State_Visible": "false",
"Zip_Visible": "false",
"Country_Visible": "false",
"Company_Visible": "false",
"Phone_Visible": "false",
"Fax_Visible": "false",
"EMail_Visible": "false",
"Website_Visible": "false",
"Tax_Visible": "false",
"Shipping_Visible": "false",
"OrderID_Visible": "false",
"PONumber_Visible": "false",
"InvoiceID_Visible": "false",
"ShippingFirstName_Visible": "false",
"ShippingLastName_Visible": "false",
"ShippingCompany_Visible": "false",
"ShippingAddress1_Visible": "false",
"ShippingAddress2_Visible": "false",
"ShippingCity_Visible": "false",
"ShippingState_Visible": "false",
"ShippingZip_Visible": "false",
"ShippingCountry_Visible": "false",
"ShippingEmail_Visible": "false",
"ShippingPhone_Visible": "false",
"ShippingFax_Visible": "false",
"ShippingTrackingNumber_Visible": "false",
"ShippingCarrier_Visible": "false"
}
}'