Hosted Payment Page – Create HPP Instance

Once you have a PayerId, you can proceed by creating a checkout page that uses the HPP. Your next step is to provision an instance of our page and define many of its characteristics. Here are a few of the properties that you can define:
  • Whether you want to require the cardholder to enter address information.
  • Whether you want to apply an invoice number to the transaction resulting from the HPP's execution (And what that invoice number should be).
  • Whether or not you wish to store the card number entered as a ProtectPay® token that can be used for future transactions.
  • You can provide the URL of a CSS file that you host to "skin" the appearance of the HPP.
  • The response from the ProtectPay API will include a HostedTransactionIdentifier that is used when you wish to embed the HPP onto your checkout page.
CSSUrl defines the look and feel
Passing in a CSSUrl parameter allows you to define the look and feel by hosting your own .css file on the internet. Your file should be accessible to ProPay, and can only be used to modify those elements that our system permits. Please refer to the actual Hosted Payment Page documentation for more information about customization.

Once you've obtained your token
Redirect the cardholder's browser to the hpp url while including the transaction instance identifier as in the following example: https://protectpay.propay.com/hpp/v2/[hostedtransactionidentifier]
How to call this method?

HTTP URL(s)
HTTP Verb PUT
HTTP Header Authorization
Example Request

Example Response

{
"PayerAccountId":5996192497201934,
"MerchantProfileId":2194337,
"Amount":100,
"CurrencyCode":"USD",
"InvoiceNumber":"496d0ca5-48b9-4aca-afca-5d7094c212e2",
"Comment1":"PropaySdkCreateHostedTransaction 1",
"Comment2":"PropaySdkCreateHostedTransaction 2",
"CardHolderNameRequirementType":1,
"SecurityCodeRequirementType":1,
"AvsRequirementType":1,
"AuthOnly":true,
"ProcessCard":true,
"StoreCard":true,
"OnlyStoreCardOnSuccessfulProcess":true,
"CssUrl":"https://epay.propay.com/App_Themes/default/Menu.css",
"FraudDetectors":null,
"PaymentTypeId":0,
"Protected":false,
"ReturnURL":"www.propay.com"
}

{
"HostedTransactionIdentifier": "5a6de34b-d6c5-4522-885d-0d90302c95b0",
"Result": {
"ResultValue": "SUCCESS",
"ResultCode": "00",
"ResultMessage": ""
}
}

Implementation Details
Request Submission

namespace ProtectPayApi_CreateHostedTransaction
{
using System;
using System.Collections.Generic;
using System.Text;

using RestSharp;

/*
ProPay provides the following code “AS IS.”
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/
public class CreateHostedTransactionProgram
{
public static void Main(string[] args)
{
var createHostedTransactionResponse = CreateHostedTransaction();
}

private static CreateHostedTransactionResponse CreateHostedTransaction()
{
var baseUrl = "https://xmltestapi.propay.com/ProtectPay";
var request = BuildCreateHostedTransactonRequest();
var restRequest = CreateRestRequest("/HostedTransactions/", RestSharp.Method.PUT);
restRequest.AddBody(request);
return Execute<CreateHostedTransactionResponse>(restRequest, baseUrl);
}

private static CreateHostedTransactionRequest BuildCreateHostedTransactonRequest()
{
return new CreateHostedTransactionRequest
{
PayerAccountId = 3702457414469838,
MerchantProfileId = 1368589,
Amount = 100,
CurrencyCode = "USD",
Comment1 = "PropaySdkCreateHostedTransaction 1",
Comment2 = "PropaySdkCreateHostedTransaction 2",
InvoiceNumber = Guid.NewGuid().ToString(),
AuthOnly = true,
ProcessCard = true,
StoreCard = true,
OnlyStoreCardOnSuccessfulProcess = true,
CardHolderNameRequirementType = RequirementType.Required,
SecurityCodeRequirementType = RequirementType.Required,
AvsRequirementType = RequirementType.Required,
CssUrl = "https://epay.propay.com/App_Themes/default/Menu.css"
};
}

/// <summary>
/// Request factory to ensure API key is always first parameter added.
/// </summary>
/// <param name="resource">The resource name.</param>
/// <param name="method">The HTTP method.</param>
/// <returns>Returns a new <see cref="RestRequest"/>.</returns>
private static RestRequest CreateRestRequest(string resource, Method method)
{
var restRequest = new RestRequest { Resource = resource, Method = method, RequestFormat = DataFormat.Json, };
var credentials = GetCredentials();
restRequest.AddHeader("accept", "application/json");
restRequest.AddHeader("Authorization", credentials);

return restRequest;
}

/// <summary>
/// Gets the credentials for the call.
/// </summary>
/// <returns>The credentials.</returns>
private static string GetCredentials()
{
var billerAccountId = "5114248593164903"; // biller account id
var authToken = "9d506d3e-b5f7-4474-adb1-76423e113c85"; // authentication token of biller

var encodedCredentials = Convert.ToBase64String(Encoding.Default.GetBytes(billerAccountId + ":" + authToken));

var credentials = string.Format("Basic {0}", encodedCredentials);
return credentials;
}

/// <summary>
/// Executes a particular http request to a resource.
/// </summary>
/// <typeparam name="T">The response type.</typeparam>
/// <param name="request">The REST request.</param>
/// <param name="baseUrl">The base URL.</param>
/// <returns>Returns a response of the type parameter.</returns>
private static T Execute<T>(IRestRequest request, string baseUrl) where T : class, new()
{
var client = new RestClient(baseUrl);
var response = client.Execute<T>(request);

if (response.ErrorException != null)
{
Console.WriteLine(
"Error: Exception: {0}, Headers: {1}, Content: {2}, Status Code: {3}",
response.ErrorException,
response.Headers,
response.Content,
response.StatusCode);
}

return response.Data;
}

/// <summary>
/// Request information for a call to the "CreateHostedTransaction" method.
/// </summary>
public class CreateHostedTransactionRequest
{
/// <summary>
/// Optional value to designate the payer of the payment method.
/// </summary>
public long? PayerAccountId { get; set; }

/// <summary>
/// Optional value to designate the merchant profile id that should be used to process the transaction.
/// </summary>
public long? MerchantProfileId { get; set; }

/// <summary>
/// The amount being processed.
/// </summary>
public long Amount { get; set; }

/// <summary>
/// The currency code of the transaction.
/// </summary>
public string CurrencyCode { get; set; }

/// <summary>
/// The invoice number of the transaction (50 length).
/// </summary>
public string InvoiceNumber { get; set; }

/// <summary>
/// Comment 1 field (128 length).
/// </summary>
public string Comment1 { get; set; }

/// <summary>
/// Comment 2 field (128 length).
/// </summary>
public string Comment2 { get; set; }

/// <summary>
/// Indicates if the 'CardHolderName' section should be required, optional, or hidden.
/// </summary>
public RequirementType CardHolderNameRequirementType { get; set; }

/// <summary>
/// Indicates if the 'SecurityCode' section should be required, optional, or hidden.
/// </summary>
public RequirementType SecurityCodeRequirementType { get; set; }

/// <summary>
/// Indicates if the 'AVS' section should be required, optional, or hidden.
/// </summary>
public RequirementType AvsRequirementType { get; set; }

/// <summary>
/// TRUE = Only authorize the card transaction, do NOT capture it. If TRUE, the "ProcessCard" property is ignored.
/// </summary>
public bool AuthOnly { get; set; }

/// <summary>
/// TRUE = Process (authorize and capture) the card transaction. This property is ignored if the "AuthOnly" property is TRUE.
/// </summary>
public bool ProcessCard { get; set; }

/// <summary>
/// TRUE = Always store the card information. This parameter is ignored if the "OnlyStoreCardOnSuccessfulProcess" property is TRUE.
/// </summary>
public bool StoreCard { get; set; }

/// <summary>
/// TRUE = Only stored the card information if the card transaction was successful. If TRUE, the "StoreCard" property is ignored.
/// </summary>
public bool OnlyStoreCardOnSuccessfulProcess { get; set; }

/// <summary>
/// The URL to use for the CSS that drives the look of the page (1024 length).
/// </summary>
public string CssUrl { get; set; }

/// <summary>
/// Gets or sets the FraudDetectors.
/// </summary>
public IEnumerable<FraudDetector> FraudDetectors { get; set; }

/// <summary>
/// Gets or sets the PaymentMethodType.
/// </summary>
public int PaymentTypeId { get; set; }

/// <summary>
/// Gets or sets a value indicating whether or not this payment method can be edited or deleted by the payer.
/// </summary>
public bool Protected { get; set; }
}

/// <summary>
/// The requirement type of the 'CardHolderName', 'SecurityCode', and 'AVS' sections.
/// </summary>
public enum RequirementType
{
/// <summary>
/// The section is required (it is displayed, and user must fill it out).
/// </summary>
Required = 1,

/// <summary>
/// The section is optional (it is displayed, and user may or may not fill it out).
/// </summary>
Optional = 2,

/// <summary>
/// The section is hidden (it is not displayed to the user).
/// </summary>
Hidden = 3
}

/// <summary>
/// The data needed for Fraud Detection.
/// </summary>
public class FraudDetector
{
/// <summary>
/// Gets or sets the third party fraud detector.
/// </summary>
public virtual string FraudDetectorProviderName { get; set; }

/// <summary>Gets or sets the input IP address for Fraud Detector.</summary>
public string InputIpAddress { get; set; }

/// <summary>
/// Gets or sets the Shipping Address 1.
/// </summary>
public string ShippingAddress1 { get; set; }

/// <summary>
/// Gets or sets the Shipping Address 2.
/// </summary>
public string ShippingAddress2 { get; set; }

/// <summary>
/// Gets or sets the Shipping City.
/// </summary>
public string ShippingCity { get; set; }

/// <summary>
/// Gets or sets the Shipping State.
/// </summary>
public string ShippingState { get; set; }

/// <summary>
/// Gets or sets the Shipping Zip.
/// </summary>
public string ShippingZip { get; set; }

/// <summary>
/// Gets or sets the Shipping Country.
/// </summary>
public string ShippingCountry { get; set; }

/// <summary>
/// Gets or sets the First name.
/// </summary>
public string ShippingFirstName { get; set; }

/// <summary>
/// Gets or sets the Last name.
/// </summary>
public string ShippingLastName { get; set; }

/// <summary>
/// Gets or sets the Shipping Phone Number.
/// </summary>
public string ShippingPhoneNumber { get; set; }
}

/// <summary>
/// The value returned from a call to the "CreateHostedTransaction" method.
/// </summary>
public class CreateHostedTransactionResponse
{
/// <summary>
/// The identifier used by the customer to get the results of the hosted transaction after it is completed.
/// </summary>
public string HostedTransactionIdentifier { get; set; }

/// <summary>
/// <c>Result</c> structure for giving the result of the transaction.
/// </summary>
public Result Result { get; set; }
}

/// <summary>
/// The result of the call.
/// </summary>
public class Result
{
/// <summary>
/// The result of the transaction
/// </summary>
/// <remarks>
/// Will always be SUCCESS or FAILURE
/// </remarks>
public string ResultValue { get; set; }

/// <summary>
/// The result code of the transaction
/// </summary>
/// <remarks>
/// Will be a two-digit string with only numbers. Allows "00" as a response.
/// </remarks>
public string ResultCode { get; set; }

/// <summary>
/// The english-text message of what went wrong (if anything)
/// </summary>
/// <remarks>
/// The documenation show the empty string being returned in the success cases.
/// </remarks>
public string ResultMessage { get; set; }
}
}
}

Response Handling

Request Submission

/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

<?php
class ProtectPayApi
{

/* change this to the production url for going live after testing https://api.propay.com */
private $_apiBaseUrl = 'https://xmltestapi.propay.com';

/* credentials that would normally be set from database values or a config value */
private $_billerId;
private $_authToken;

/* for creating hosted transactions */
private $_createHostedTransactionData;
private $_createdHostedTransactionInfo;

/**
* @param string $billerId
* @return $this
*/
public function setBillerId($billerId) {
$this->_billerId = $billerId;
return $this;
}

/**
* @param string $authToken
* @return $this
*/
public function setAuthToken($authToken) {
$this->_authToken = $authToken;
return $this;
}

/**
* @return string
*/
private function _getAuth() {
return $this->_billerId . ':' . $this->_authToken;
}

/**
* @return mixed
*/
public function getCreatedHostedTransactionInfo() {
return $this->_createdHostedTransactionInfo;
}

/**
* @param array $hostedTransactionData
* @return $this
*/
public function setHostedTransactionData($hostedTransactionData) {
$this->_createHostedTransactionData = $hostedTransactionData;
return $this;
}

/**
* Created the hosted transaction
* @return $this
* _createdHostedTransactionInfo contains a json string like this
* {
"HostedTransactionIdentifier":"f1549c53-e499-476d-84cc-93f99586505d",
"Result":
{
"ResultValue":"SUCCESS",
"ResultCode":"00",
"ResultMessage":""
}
}
*/
public function createHostedTransaction() {
$data_string = json_encode($this->_createHostedTransactionData);

$ch = curl_init($this->_apiBaseUrl . '/protectpay/hostedtransactions');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $this->_getAuth());
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data_string)
));

$this->_createdHostedTransactionInfo = curl_exec($ch);
return $this;
}
}


$data = [
"PayerAccountId" => 999999927655035,
"MerchantProfileId" => 123456,
"Amount" => 100,
"CurrencyCode" => "USD",
"InvoiceNumber" => "Test Invoice",
"Comment1" => "Test Comment 1",
"Comment2" => "Test comment 2",
"CardHolderNameRequirementType" => 1,
"SecurityCodeRequirementType" => 1,
"AvsRequirementType" => 1,
"AuthOnly" => true,
"ProcessCard" => true,
"StoreCard" => true,
"OnlyStoreCardOnSuccessfulProcess" => true,
"CssUrl" => "https://protectpaytest.propay.com/hpp/css/pmi.css",
"Address1" => "123 ABC St",
"Address2" => "Apt A",
"City" => "Faloola",
"Country" => "USA",
"Description" => "My Visa",
"Name" => "John Smith",
"State" => "UT",
"ZipCode" => "12345",
"BillerIdentityId" => null,
"CreationDate" => null,
"HostedTransactionIdentifier" => null,
"PaymentTypeId" => "0",
"Protected" => false
];

// Create Hosted transaction
$protectPayAPI = new ProtectPayApi();
$result = $protectPayAPI->setBillerId('9999986379225246')
->setAuthToken('16dfe8d7-889b-4380-925f-9c2c6ea4d930')
->setHostedTransactionData($data)
->createHostedTransaction()
->getCreatedHostedTransactionInfo();

Response Handling

Request Submission

/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

import java.io.IOException;
import java.util.UUID;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.ObjectMapper;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;
import com.mashape.unirest.request.HttpRequest;
import com.mashape.unirest.request.HttpRequestWithBody;

public class CreateHostedTransactionSample {
 /**
* This URL would normally come from some configuration file or database.
*/
 final String baseUrl = "https://xmltestapi.propay.com/protectpay/";

 public static void main(String[] args) {
configureObjectMapper();

CreateHostedTransactionSample program = new CreateHostedTransactionSample();
CreateHostedTransactionResponse response = program.createHostedTransaction();

Result requestResult = response.Result;

System.out.println("Result: " + requestResult.ResultValue);
System.out.println("Result code: " + requestResult.ResultCode);
System.out.println("Result message: " + requestResult.ResultMessage);

System.out.println("Hosted transaction identifier: " + response.HostedTransactionIdentifier);
 }

 public CreateHostedTransactionResponse createHostedTransaction() {
String resourceUrl = baseUrl + "HostedTransactions";

HttpRequestWithBody request = this.createRequest(resourceUrl);

CreateHostedTransactionRequest hostedTransactionRequest = this.buildRequest();

request.body(hostedTransactionRequest);

return this.executeRequest(request, CreateHostedTransactionResponse.class);
 }

 private CreateHostedTransactionRequest buildRequest() {
final long TenDollars = 1000;

long payerId = this.getPayerAccountId();
String invoiceNumber = this.getInvoiceNumber();

CreateHostedTransactionRequest request = new CreateHostedTransactionRequest();
request.PayerAccountId = payerId;
request.Amount = TenDollars;
request.CurrencyCode = "USD";
request.Comment1 = "PropaySdkCreateHostedTransaction 1";
request.Comment2 = "PropaySdkCreateHostedTransaction 2";
request.InvoiceNumber = invoiceNumber;
request.AuthOnly = true;
request.ProcessCard = true;
request.StoreCard = true;
request.OnlyStoreCardOnSuccessfulProcess = true;
request.CardHolderNameRequirementType = CreateHostedTransactionRequest.RequirementType.Required;
request.SecurityCodeRequirementType = CreateHostedTransactionRequest.RequirementType.Required;
request.AvsRequirementType = CreateHostedTransactionRequest.RequirementType.Required;
request.CssUrl = "https://epay.propay.com/App_Themes/default/Menu.css";

return request;
 }

 /**
* Gets the authentication token. This would normally be in a configuration
* file or database.
*
* @return The authentication token.
*/
 private String getAuthToken() {
return "EFA7EEDD-065C-4361-AC24-E13BCC4EF520";
 }

 /**
* Gets the biller's id. This would normally be in a configuration file or
* database.
*/
 private String getBillerId() {
return "9876543210987654";
 }

 /**
* Gets the payer's id.
*
* This would normally be in a database or generated as a result of an
* earlier call, see ProtectPay API Manual sections "Create a PayerId" or
* "Create TempToken".
*/
 private long getPayerAccountId() {
return 1234567890789787L;
 }

 /**
* Get the invoice number.
*
* This is whatever invoice numbering your company uses.
*/
 private String getInvoiceNumber() {
return UUID.randomUUID().toString();
 }

 /**
* Create the request instance. This ensures that the authentication header
* is attached to each request.
*
* @param resourceUrl
* The URL of the REST resource.
* @return The GetRequest instance.
*/
 private HttpRequestWithBody createRequest(String resourceUrl) {
String authToken = this.getAuthToken();
String billerId = this.getBillerId();

HttpRequestWithBody restRequest = Unirest.put(resourceUrl).basicAuth(billerId, authToken)
.header("accept", "application/json").header("Content-Type", "application/json");

return restRequest;
 }

 /**
* Execute a REST request.
*
* @param request
* The request to perform.
* @param responseClass
* The type instance of the return type.
* @return An instance of type T or null if there was an error.
*/
 private <T> T executeRequest(HttpRequest request, Class<T> responseClass) {
try {
HttpResponse<T> response = request.asObject(responseClass);
if (response.getStatus() != 200) { // HTTP OK response code
System.out.println(response.getStatusText());
return null;
}

return response.getBody();
} catch (UnirestException e) {
e.printStackTrace();
}

return null;
 }

 /**
* Configures the mapping between JSON and Classes.
*
* This is boilerplate Unirest & Jackson configuration. It should only need
* to be done once in a full solution.
*/
 private static void configureObjectMapper() {
Unirest.setObjectMapper(new ObjectMapper() {
private com.fasterxml.jackson.databind.ObjectMapper jacksonObjectMapper = new com.fasterxml.jackson.databind.ObjectMapper();

public <T> T readValue(String value, Class<T> valueType) {
try {
return jacksonObjectMapper.readValue(value, valueType);
} catch (IOException e) {
throw new RuntimeException(e);
}
}

public String writeValue(Object value) {
try {
return jacksonObjectMapper.writeValueAsString(value);
} catch (JsonProcessingException e) {
throw new RuntimeException(e);
}
}
});
 }
}

// -------------------------------------------------------------------------------------------- //
// Object files

// CreateHostedTransactionRequest.java


/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

/**
 * Request to create a hosted transaction so your customer can use the Hosted
 * Payment Page (HPP) to enter payment information.
 */
public class CreateHostedTransactionRequest {
 public enum RequirementType {
/**
* The section is required (it is displayed, and user must fill it out).
*/
Required(1),

/**
* The section is optional (it is displayed, and user may or may not
* fill it out).
*/
Optional(2),

/**
* The section is hidden (it is not displayed to the user).
*/
Hidden(3);

/**
* The integer value for the enumeration.
*/
private int value;

private RequirementType(int value) {
this.value = value;
}

/**
* @return the value
*/
public int getValue() {
return value;
}
 }

 /**
* Optional value to designate the payer of the payment method.
*/
 public long PayerAccountId;
 /**
* Optional value to designate the merchant profile id that should be used
* to process the transaction.
*/
 public long MerchantProfileId;
 /**
* The amount of the transaction.
*/
 public long Amount;
 /**
* The currency code of the transaction.
*/
 public String CurrencyCode;
 /**
* Comment to associate with the transaction.
*/
 public String Comment1;
 /**
* Comment to associate with the transaction.
*/
 public String Comment2;
 /**
* The invoice number of the transaction.
*/
 public String InvoiceNumber;
 /**
* Whether to perform an authorize only transaction (true) or to
* capture/settle the transaction (false).
*
* If true the ProcessCard field is ignored.
*/
 public boolean AuthOnly;

 /**
* Whether to capture/settle the transaction.
*
* If AuthOnly is true this field is ignored.
*/
 public boolean ProcessCard;

 /**
* Whether to always store the card information.
*
* This is ignored if the OnlyStoreCardOnSuccessfulProcess field is true.
*/
 public boolean StoreCard;

 /**
* Whether to save the tokenized card only if the card transaction succeeds.
*/
 public boolean OnlyStoreCardOnSuccessfulProcess;

 /**
* Indicates if the 'CardHolderName' section should be required, optional,
* or hidden.
*/
 public RequirementType CardHolderNameRequirementType;

 /**
* Indicates if the 'SecurityCode' section should be required, optional, or
* hidden.
*/
 public RequirementType SecurityCodeRequirementType;

 /**
* Indicates if the 'AVS' section should be required, optional, or hidden.
*/
 public RequirementType AvsRequirementType;

 /**
* The URL to use for the CSS that drives the look of the page (max 1024
* characters).
*/
 public String CssUrl;
}

// -------------------------------------------------------------------------------------------- //
// Result.java

/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

/**
 * The result of the call.
 */
public class Result {
 /**
* The result of the transaction
*
* Will always be SUCCESS or FAILURE
*/
 public String ResultValue;

 /**
* The result code of the transaction
*
*
* Will be a two-digit string with only numbers. Allows "00" as a response.
*/
 public String ResultCode;

 /**
* The English-text message of what went wrong (if anything)
*
*
* The documentation shows the empty string being returned in the success
* cases.
*/
 public String ResultMessage;
}

// -------------------------------------------------------------------------------------------- //
// CreateHostedTransactionResponse.java

/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

public class CreateHostedTransactionResponse {
 /**
* The API Result from the method call.
*/
 public Result Result;

 /**
* The identifier used to get the results of the hosted transaction after it
* is completed.
*/
 public String HostedTransactionIdentifier;
}

Response Handling

The following sample uses the Unirest and Jackson libraries.

You can add them to your project using:

Apache Maven
<dependency>
<groupId>com.mashape.unirest</groupId>
<artifactId>unirest-java</artifactId>
<version>1.4.9</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.8.8.1</version>
</dependency>


Gradle/Grails
compile 'com.mashape.unirest:unirest-java:1.4.9'
compile 'com.fasterxml.jackson.core:jackson-databind:2.8.8.1'

Request Submission

Response Handling

Request Values

Request Element

Type

Max

Required

Notes

AuthenticationToken

String

100

Authorization

Valid value is a GUID. Value supplied by ProPay. Used to access the API

BillerAccountId

String

16

Authorization

Value supplied by ProPay. Used to identify the correct collection of tokens.

Amount

Integer

 

Required

The value representing the number of pennies in USD, or the number of [currency] without decimals.

AcceptMasterPass

Boolean

 

Optional

Valid values are:
True
False

User can use MasterPass making CreateHostedTransactionIdentifier call with AcceptmasterPass true .This property is ignored if merchant is not subscribed for Masterpass.

AvsRequirementType

Integer

1

Required

Indicates if the 'AVS' section should be required, optional, or hidden.
1=AVS displayed, required
2=AVS displayed, optional
3=AVS hidden

BillerAccountId

String

-

Optional

Intended Future Use

BillerAuthToken

String

-

Optional

Intended Future Use

BillerIdentityId

Long

-

Optional

Intended Future Use

CardHolderNameRequirementType

Integer

1

Required

Indicates if the 'CardHolderName' section should be required, optional, or hidden.
1= CH Name displayed, required
2= CH Name displayed, optional
3=CH Name hidden

 

Comment1

String

128

Optional

Comment 1 to be displayed to the user on the Hosted Page.

Comment2

String

128

Optional

Comment 2 to be displayed to the user on the Hosted Page.

CreationDate

DateTime

-

 

 

CssUrl

String

1024

Optional

The fully qualified URL to use for the CSS that drives the look of the page.
Must be hosted HTTPS
Sending empty value removes default style

 

CurrencyCode

String

3

Required

ISO 4217 standard 3 character currency code.

Frauddetectors

Object

-

Optional

Please See ProtectPay ProtectPay Appendix A for details concerning the FrauddetectorsObject

Frauddetectorss.FrauddetectorProviderName

String

 

Required*

If using Frauddetectors Object this Element is required.

HostedTransactionIdentifier

String

-

 

The hosted transaction ID (GUID) that was returned from the call to "CreateHostedTransactionIdentifier"

InvoiceNumber

String

50

Optional

Highly recommended. Transaction descriptor-only passed if supported by the gateway.

MerchantProfileId

Long

-

Required

Used to specify which processor and merchant account to process the transaction against.

OnlyStoreCardOnSuccessfulProcess

Boolean

-

Required

Valid values are:
true
false

Only stored the card information if the card transaction was successful.

* This is ignored if the "StoreCard" property is set to true

PaymentTypeId

String

1

Required

Valid Values are:
0=credit card
1=ACH

If set to 1 overrides display options and displays Name and ACH field only

PayerId

 

Long

16

Required

The Payer under which the PaymentMethodId should be created under.

ProcessCard

Boolean

-

Required*

Valid values are:
true
false

Process (authorize and capture) the card transaction. This property is ignored if the "AuthOnly" property is true.

Protected

Boolean

5

Optional

Valid values are:
true
false

Payment methods set to ‘true’ cannot be deleted by a payer.

ReturnURL

String

1024

Optional

The fully qualified URL to redirect once transaction is completed.

* Sending an empty value will not allow to perform a transaction.

SecurityCodeRequirementType

Integer

1

Required

Indicates if the 'SecurityCode' section should be required, optional, or hidden.
1=CVV displayed, required
2=CVV displayed, optional
3=CVV hidden

StoreCard

Boolean

 

Required*

Valid values are:
true
false

Always store the card information. This is ignored if the "OnlyStoreCardOnSuccessfulProcess" property is true.

If [AuthOnly], [ProcessCard] and [StoreCard] are set to False the hosted page will not do anything

 

Request values defined (Optional Elements to pre-load the Hosted Payment Page)

Request Element

Type

Max

Required

Notes

Address1

String

50

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Address 1 Field.

*Max length is 40 for multi-currency transactions.

Address2

String

50

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Address 2 Field.

*Max length is 40 for multi-currency transactions.

City

String

25

Optional

If this value is supplied the Hosted Payment Page will load with this value in the City Field

Country

String

3

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Country Field

*Must be ISO 3166 standard 3 character country code.

Description

String

100

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Description Field

Name

String

3

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Name Field

State

String

20*

Optional

If this value is supplied the Hosted Payment Page will load with this value in the State Field

Country Code is Required if preloading the State Selection Box

Limited to USA/CAN only

ZipCode

String

10

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Postal Code Field

Response Values

Response Element

Type

Notes

RequestResult.ResultValue

String

The ProtectPay API Method Response Value;

SUCCESS indicates the method completed;

FAILURE indicates the method call failed and the reason is indicated in the ResultCode and ResultMessage

RequestResult.ResultCode

String

The ProtectPay API Method Response Code. See ProtectPay Appendix A for possible returned Values

RequestResult.ResultMessage

String

The ProtectPay API Method Response Message. See ProtectPay Appendix A for possible returned Messages

HostedTransactionIdentifier

String

Unique One Time use only identifier for a Hosted Transaction Page

How to call this method?

Example Request

Example Response

Implementation Details
Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Values
Response Values
How to call this method?

{SOAP Action}     CreateHostedTransaction
{URL}                   https://xmltestapi.propay.com/protectpay/sps.svc
Example Request

Example Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://propay.com/SPS/contracts" xmlns:typ="http://propay.com/SPS/types" xmlns:prop="http://schemas.datacontract.org/2004/07/Propay.Contracts.SPS.External" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header/>
<soapenv:Body>
<con:CreateHostedTransaction>
<con:id>
<typ:AuthenticationToken>MyAuthToken</typ:AuthenticationToken>
<typ:BillerAccountId>MyBillerId</typ:BillerAccountId>
</con:id>
<con:hostedTransaction>
<prop:Address1>123 ABC St</prop:Address1>
<prop:Address2>Apt A</prop:Address2>
<prop:Amount>10000</prop:Amount>
<prop:AuthOnly>false</prop:AuthOnly>
<prop:AvsRequirementType>Required</prop:AvsRequirementType>
<prop:BillerAccountId>MyBillerId</prop:BillerAccountId>
<prop:BillerAuthToken>MyAuthToken</prop:BillerAuthToken>
<prop:BillerIdentityId/>
<prop:CardHolderNameRequirementType>Required</prop:CardHolderNameRequirementType>
<prop:City>Faloola</prop:City>
<prop:Comment1>Test Comment 1</prop:Comment1>
<prop:Comment2>Test Comment 2</prop:Comment2>
<prop:Country>USA</prop:Country>
<prop:CreationDate/>
<prop:CssUrl>https://protectpaytest.propay.com/hpp/css/pmi.css</prop:CssUrl>
<prop:CurrencyCode>USD</prop:CurrencyCode>
<prop:Description>My Visa</prop:Description>
<prop:HostedTransactionIdentifier/>
<prop:InvoiceNumber>Test Invoice</prop:InvoiceNumber>
<prop:MerchantProfileId>12345</prop:MerchantProfileId>
<prop:Name>John Smith</prop:Name>
<prop:OnlyStoreCardOnSuccessfulProcess>false</prop:OnlyStoreCardOnSuccessfulProcess>
<prop:PayerId>12345678</prop:PayerId>
<prop:PaymentTypeId>0</prop:PaymentTypeId>
<prop:ProcessCard>true</prop:ProcessCard>
<prop:Protected>false</prop:Protected>
<prop:ReturnUrl>www.propay.com</prop:ReturnUrl>
<prop:SecurityCodeRequirementType>1</prop:SecurityCodeRequirementType>
<prop:State>UT</prop:State>
<prop:StoreCard>true</prop:StoreCard>
<prop:ZipCode>12345</prop:ZipCode>
</con:hostedTransaction>
</con:CreateHostedTransaction>
</soapenv:Body>
</soapenv:Envelope>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CreateHostedTransactionResponse xmlns="http://propay.com/SPS/contracts">
<CreateHostedTransactionResult xmlns:a="http://propay.com/SPS/types" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:HostedTransactionIdentifier>3bb49a32-b4ce-4ec9-92bd-0774fd5fd1ad</a:HostedTransactionIdentifier>
<a:Result>
<a:ResultCode>00</a:ResultCode>
<a:ResultMessage/>
<a:ResultValue>SUCCESS</a:ResultValue>
</a:Result>
</CreateHostedTransactionResult>
</CreateHostedTransactionResponse>
</s:Body>
</s:Envelope>
Implementation Details
Request Submission

namespace ProtectPayApi_CreateHostedTransaction
{
using System;
using System.Collections.Generic;
using System.Text;

using RestSharp;

/*
ProPay provides the following code “AS IS.”
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/
public class CreateHostedTransactionProgram
{
public static void Main(string[] args)
{
var createHostedTransactionResponse = CreateHostedTransaction();
}

private static CreateHostedTransactionResponse CreateHostedTransaction()
{
var baseUrl = "https://xmltestapi.propay.com/ProtectPay";
var request = BuildCreateHostedTransactonRequest();
var restRequest = CreateRestRequest("/HostedTransactions/", RestSharp.Method.PUT);
restRequest.AddBody(request);
return Execute<CreateHostedTransactionResponse>(restRequest, baseUrl);
}

private static CreateHostedTransactionRequest BuildCreateHostedTransactonRequest()
{
return new CreateHostedTransactionRequest
{
PayerAccountId = 3702457414469838,
MerchantProfileId = 1368589,
Amount = 100,
CurrencyCode = "USD",
Comment1 = "PropaySdkCreateHostedTransaction 1",
Comment2 = "PropaySdkCreateHostedTransaction 2",
InvoiceNumber = Guid.NewGuid().ToString(),
AuthOnly = true,
ProcessCard = true,
StoreCard = true,
OnlyStoreCardOnSuccessfulProcess = true,
CardHolderNameRequirementType = RequirementType.Required,
SecurityCodeRequirementType = RequirementType.Required,
AvsRequirementType = RequirementType.Required,
CssUrl = "https://epay.propay.com/App_Themes/default/Menu.css"
};
}

/// <summary>
/// Request factory to ensure API key is always first parameter added.
/// </summary>
/// <param name="resource">The resource name.</param>
/// <param name="method">The HTTP method.</param>
/// <returns>Returns a new <see cref="RestRequest"/>.</returns>
private static RestRequest CreateRestRequest(string resource, Method method)
{
var restRequest = new RestRequest { Resource = resource, Method = method, RequestFormat = DataFormat.Json, };
var credentials = GetCredentials();
restRequest.AddHeader("accept", "application/json");
restRequest.AddHeader("Authorization", credentials);

return restRequest;
}

/// <summary>
/// Gets the credentials for the call.
/// </summary>
/// <returns>The credentials.</returns>
private static string GetCredentials()
{
var billerAccountId = "5114248593164903"; // biller account id
var authToken = "9d506d3e-b5f7-4474-adb1-76423e113c85"; // authentication token of biller

var encodedCredentials = Convert.ToBase64String(Encoding.Default.GetBytes(billerAccountId + ":" + authToken));

var credentials = string.Format("Basic {0}", encodedCredentials);
return credentials;
}

/// <summary>
/// Executes a particular http request to a resource.
/// </summary>
/// <typeparam name="T">The response type.</typeparam>
/// <param name="request">The REST request.</param>
/// <param name="baseUrl">The base URL.</param>
/// <returns>Returns a response of the type parameter.</returns>
private static T Execute<T>(IRestRequest request, string baseUrl) where T : class, new()
{
var client = new RestClient(baseUrl);
var response = client.Execute<T>(request);

if (response.ErrorException != null)
{
Console.WriteLine(
"Error: Exception: {0}, Headers: {1}, Content: {2}, Status Code: {3}",
response.ErrorException,
response.Headers,
response.Content,
response.StatusCode);
}

return response.Data;
}

/// <summary>
/// Request information for a call to the "CreateHostedTransaction" method.
/// </summary>
public class CreateHostedTransactionRequest
{
/// <summary>
/// Optional value to designate the payer of the payment method.
/// </summary>
public long? PayerAccountId { get; set; }

/// <summary>
/// Optional value to designate the merchant profile id that should be used to process the transaction.
/// </summary>
public long? MerchantProfileId { get; set; }

/// <summary>
/// The amount being processed.
/// </summary>
public long Amount { get; set; }

/// <summary>
/// The currency code of the transaction.
/// </summary>
public string CurrencyCode { get; set; }

/// <summary>
/// The invoice number of the transaction (50 length).
/// </summary>
public string InvoiceNumber { get; set; }

/// <summary>
/// Comment 1 field (128 length).
/// </summary>
public string Comment1 { get; set; }

/// <summary>
/// Comment 2 field (128 length).
/// </summary>
public string Comment2 { get; set; }

/// <summary>
/// Indicates if the 'CardHolderName' section should be required, optional, or hidden.
/// </summary>
public RequirementType CardHolderNameRequirementType { get; set; }

/// <summary>
/// Indicates if the 'SecurityCode' section should be required, optional, or hidden.
/// </summary>
public RequirementType SecurityCodeRequirementType { get; set; }

/// <summary>
/// Indicates if the 'AVS' section should be required, optional, or hidden.
/// </summary>
public RequirementType AvsRequirementType { get; set; }

/// <summary>
/// TRUE = Only authorize the card transaction, do NOT capture it. If TRUE, the "ProcessCard" property is ignored.
/// </summary>
public bool AuthOnly { get; set; }

/// <summary>
/// TRUE = Process (authorize and capture) the card transaction. This property is ignored if the "AuthOnly" property is TRUE.
/// </summary>
public bool ProcessCard { get; set; }

/// <summary>
/// TRUE = Always store the card information. This parameter is ignored if the "OnlyStoreCardOnSuccessfulProcess" property is TRUE.
/// </summary>
public bool StoreCard { get; set; }

/// <summary>
/// TRUE = Only stored the card information if the card transaction was successful. If TRUE, the "StoreCard" property is ignored.
/// </summary>
public bool OnlyStoreCardOnSuccessfulProcess { get; set; }

/// <summary>
/// The URL to use for the CSS that drives the look of the page (1024 length).
/// </summary>
public string CssUrl { get; set; }

/// <summary>
/// Gets or sets the FraudDetectors.
/// </summary>
public IEnumerable<FraudDetector> FraudDetectors { get; set; }

/// <summary>
/// Gets or sets the PaymentMethodType.
/// </summary>
public int PaymentTypeId { get; set; }

/// <summary>
/// Gets or sets a value indicating whether or not this payment method can be edited or deleted by the payer.
/// </summary>
public bool Protected { get; set; }
}

/// <summary>
/// The requirement type of the 'CardHolderName', 'SecurityCode', and 'AVS' sections.
/// </summary>
public enum RequirementType
{
/// <summary>
/// The section is required (it is displayed, and user must fill it out).
/// </summary>
Required = 1,

/// <summary>
/// The section is optional (it is displayed, and user may or may not fill it out).
/// </summary>
Optional = 2,

/// <summary>
/// The section is hidden (it is not displayed to the user).
/// </summary>
Hidden = 3
}

/// <summary>
/// The data needed for Fraud Detection.
/// </summary>
public class FraudDetector
{
/// <summary>
/// Gets or sets the third party fraud detector.
/// </summary>
public virtual string FraudDetectorProviderName { get; set; }

/// <summary>Gets or sets the input IP address for Fraud Detector.</summary>
public string InputIpAddress { get; set; }

/// <summary>
/// Gets or sets the Shipping Address 1.
/// </summary>
public string ShippingAddress1 { get; set; }

/// <summary>
/// Gets or sets the Shipping Address 2.
/// </summary>
public string ShippingAddress2 { get; set; }

/// <summary>
/// Gets or sets the Shipping City.
/// </summary>
public string ShippingCity { get; set; }

/// <summary>
/// Gets or sets the Shipping State.
/// </summary>
public string ShippingState { get; set; }

/// <summary>
/// Gets or sets the Shipping Zip.
/// </summary>
public string ShippingZip { get; set; }

/// <summary>
/// Gets or sets the Shipping Country.
/// </summary>
public string ShippingCountry { get; set; }

/// <summary>
/// Gets or sets the First name.
/// </summary>
public string ShippingFirstName { get; set; }

/// <summary>
/// Gets or sets the Last name.
/// </summary>
public string ShippingLastName { get; set; }

/// <summary>
/// Gets or sets the Shipping Phone Number.
/// </summary>
public string ShippingPhoneNumber { get; set; }
}

/// <summary>
/// The value returned from a call to the "CreateHostedTransaction" method.
/// </summary>
public class CreateHostedTransactionResponse
{
/// <summary>
/// The identifier used by the customer to get the results of the hosted transaction after it is completed.
/// </summary>
public string HostedTransactionIdentifier { get; set; }

/// <summary>
/// <c>Result</c> structure for giving the result of the transaction.
/// </summary>
public Result Result { get; set; }
}

/// <summary>
/// The result of the call.
/// </summary>
public class Result
{
/// <summary>
/// The result of the transaction
/// </summary>
/// <remarks>
/// Will always be SUCCESS or FAILURE
/// </remarks>
public string ResultValue { get; set; }

/// <summary>
/// The result code of the transaction
/// </summary>
/// <remarks>
/// Will be a two-digit string with only numbers. Allows "00" as a response.
/// </remarks>
public string ResultCode { get; set; }

/// <summary>
/// The english-text message of what went wrong (if anything)
/// </summary>
/// <remarks>
/// The documenation show the empty string being returned in the success cases.
/// </remarks>
public string ResultMessage { get; set; }
}
}
}

Response Handling

Request Submission

/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

<?php
class ProtectPayApi
{

/* change this to the production url for going live after testing https://api.propay.com */
private $_apiBaseUrl = 'https://xmltestapi.propay.com';

/* credentials that would normally be set from database values or a config value */
private $_billerId;
private $_authToken;

/* for creating hosted transactions */
private $_createHostedTransactionData;
private $_createdHostedTransactionInfo;

/**
* @param string $billerId
* @return $this
*/
public function setBillerId($billerId) {
$this->_billerId = $billerId;
return $this;
}

/**
* @param string $authToken
* @return $this
*/
public function setAuthToken($authToken) {
$this->_authToken = $authToken;
return $this;
}

/**
* @return string
*/
private function _getAuth() {
return $this->_billerId . ':' . $this->_authToken;
}

/**
* @return mixed
*/
public function getCreatedHostedTransactionInfo() {
return $this->_createdHostedTransactionInfo;
}

/**
* @param array $hostedTransactionData
* @return $this
*/
public function setHostedTransactionData($hostedTransactionData) {
$this->_createHostedTransactionData = $hostedTransactionData;
return $this;
}

/**
* Created the hosted transaction
* @return $this
* _createdHostedTransactionInfo contains a json string like this
* {
"HostedTransactionIdentifier":"f1549c53-e499-476d-84cc-93f99586505d",
"Result":
{
"ResultValue":"SUCCESS",
"ResultCode":"00",
"ResultMessage":""
}
}
*/
public function createHostedTransaction() {
$data_string = json_encode($this->_createHostedTransactionData);

$ch = curl_init($this->_apiBaseUrl . '/protectpay/hostedtransactions');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $this->_getAuth());
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data_string)
));

$this->_createdHostedTransactionInfo = curl_exec($ch);
return $this;
}
}


$data = [
"PayerAccountId" => 999999927655035,
"MerchantProfileId" => 123456,
"Amount" => 100,
"CurrencyCode" => "USD",
"InvoiceNumber" => "Test Invoice",
"Comment1" => "Test Comment 1",
"Comment2" => "Test comment 2",
"CardHolderNameRequirementType" => 1,
"SecurityCodeRequirementType" => 1,
"AvsRequirementType" => 1,
"AuthOnly" => true,
"ProcessCard" => true,
"StoreCard" => true,
"OnlyStoreCardOnSuccessfulProcess" => true,
"CssUrl" => "https://protectpaytest.propay.com/hpp/css/pmi.css",
"Address1" => "123 ABC St",
"Address2" => "Apt A",
"City" => "Faloola",
"Country" => "USA",
"Description" => "My Visa",
"Name" => "John Smith",
"State" => "UT",
"ZipCode" => "12345",
"BillerIdentityId" => null,
"CreationDate" => null,
"HostedTransactionIdentifier" => null,
"PaymentTypeId" => "0",
"Protected" => false
];

// Create Hosted transaction
$protectPayAPI = new ProtectPayApi();
$result = $protectPayAPI->setBillerId('9999986379225246')
->setAuthToken('16dfe8d7-889b-4380-925f-9c2c6ea4d930')
->setHostedTransactionData($data)
->createHostedTransaction()
->getCreatedHostedTransactionInfo();

Response Handling

Request Submission

/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

import java.io.IOException;
import java.util.UUID;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.ObjectMapper;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;
import com.mashape.unirest.request.HttpRequest;
import com.mashape.unirest.request.HttpRequestWithBody;

public class CreateHostedTransactionSample {
 /**
* This URL would normally come from some configuration file or database.
*/
 final String baseUrl = "https://xmltestapi.propay.com/protectpay/";

 public static void main(String[] args) {
configureObjectMapper();

CreateHostedTransactionSample program = new CreateHostedTransactionSample();
CreateHostedTransactionResponse response = program.createHostedTransaction();

Result requestResult = response.Result;

System.out.println("Result: " + requestResult.ResultValue);
System.out.println("Result code: " + requestResult.ResultCode);
System.out.println("Result message: " + requestResult.ResultMessage);

System.out.println("Hosted transaction identifier: " + response.HostedTransactionIdentifier);
 }

 public CreateHostedTransactionResponse createHostedTransaction() {
String resourceUrl = baseUrl + "HostedTransactions";

HttpRequestWithBody request = this.createRequest(resourceUrl);

CreateHostedTransactionRequest hostedTransactionRequest = this.buildRequest();

request.body(hostedTransactionRequest);

return this.executeRequest(request, CreateHostedTransactionResponse.class);
 }

 private CreateHostedTransactionRequest buildRequest() {
final long TenDollars = 1000;

long payerId = this.getPayerAccountId();
String invoiceNumber = this.getInvoiceNumber();

CreateHostedTransactionRequest request = new CreateHostedTransactionRequest();
request.PayerAccountId = payerId;
request.Amount = TenDollars;
request.CurrencyCode = "USD";
request.Comment1 = "PropaySdkCreateHostedTransaction 1";
request.Comment2 = "PropaySdkCreateHostedTransaction 2";
request.InvoiceNumber = invoiceNumber;
request.AuthOnly = true;
request.ProcessCard = true;
request.StoreCard = true;
request.OnlyStoreCardOnSuccessfulProcess = true;
request.CardHolderNameRequirementType = CreateHostedTransactionRequest.RequirementType.Required;
request.SecurityCodeRequirementType = CreateHostedTransactionRequest.RequirementType.Required;
request.AvsRequirementType = CreateHostedTransactionRequest.RequirementType.Required;
request.CssUrl = "https://epay.propay.com/App_Themes/default/Menu.css";

return request;
 }

 /**
* Gets the authentication token. This would normally be in a configuration
* file or database.
*
* @return The authentication token.
*/
 private String getAuthToken() {
return "EFA7EEDD-065C-4361-AC24-E13BCC4EF520";
 }

 /**
* Gets the biller's id. This would normally be in a configuration file or
* database.
*/
 private String getBillerId() {
return "9876543210987654";
 }

 /**
* Gets the payer's id.
*
* This would normally be in a database or generated as a result of an
* earlier call, see ProtectPay API Manual sections "Create a PayerId" or
* "Create TempToken".
*/
 private long getPayerAccountId() {
return 1234567890789787L;
 }

 /**
* Get the invoice number.
*
* This is whatever invoice numbering your company uses.
*/
 private String getInvoiceNumber() {
return UUID.randomUUID().toString();
 }

 /**
* Create the request instance. This ensures that the authentication header
* is attached to each request.
*
* @param resourceUrl
* The URL of the REST resource.
* @return The GetRequest instance.
*/
 private HttpRequestWithBody createRequest(String resourceUrl) {
String authToken = this.getAuthToken();
String billerId = this.getBillerId();

HttpRequestWithBody restRequest = Unirest.put(resourceUrl).basicAuth(billerId, authToken)
.header("accept", "application/json").header("Content-Type", "application/json");

return restRequest;
 }

 /**
* Execute a REST request.
*
* @param request
* The request to perform.
* @param responseClass
* The type instance of the return type.
* @return An instance of type T or null if there was an error.
*/
 private <T> T executeRequest(HttpRequest request, Class<T> responseClass) {
try {
HttpResponse<T> response = request.asObject(responseClass);
if (response.getStatus() != 200) { // HTTP OK response code
System.out.println(response.getStatusText());
return null;
}

return response.getBody();
} catch (UnirestException e) {
e.printStackTrace();
}

return null;
 }

 /**
* Configures the mapping between JSON and Classes.
*
* This is boilerplate Unirest & Jackson configuration. It should only need
* to be done once in a full solution.
*/
 private static void configureObjectMapper() {
Unirest.setObjectMapper(new ObjectMapper() {
private com.fasterxml.jackson.databind.ObjectMapper jacksonObjectMapper = new com.fasterxml.jackson.databind.ObjectMapper();

public <T> T readValue(String value, Class<T> valueType) {
try {
return jacksonObjectMapper.readValue(value, valueType);
} catch (IOException e) {
throw new RuntimeException(e);
}
}

public String writeValue(Object value) {
try {
return jacksonObjectMapper.writeValueAsString(value);
} catch (JsonProcessingException e) {
throw new RuntimeException(e);
}
}
});
 }
}

// -------------------------------------------------------------------------------------------- //
// Object files

// CreateHostedTransactionRequest.java


/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

/**
 * Request to create a hosted transaction so your customer can use the Hosted
 * Payment Page (HPP) to enter payment information.
 */
public class CreateHostedTransactionRequest {
 public enum RequirementType {
/**
* The section is required (it is displayed, and user must fill it out).
*/
Required(1),

/**
* The section is optional (it is displayed, and user may or may not
* fill it out).
*/
Optional(2),

/**
* The section is hidden (it is not displayed to the user).
*/
Hidden(3);

/**
* The integer value for the enumeration.
*/
private int value;

private RequirementType(int value) {
this.value = value;
}

/**
* @return the value
*/
public int getValue() {
return value;
}
 }

 /**
* Optional value to designate the payer of the payment method.
*/
 public long PayerAccountId;
 /**
* Optional value to designate the merchant profile id that should be used
* to process the transaction.
*/
 public long MerchantProfileId;
 /**
* The amount of the transaction.
*/
 public long Amount;
 /**
* The currency code of the transaction.
*/
 public String CurrencyCode;
 /**
* Comment to associate with the transaction.
*/
 public String Comment1;
 /**
* Comment to associate with the transaction.
*/
 public String Comment2;
 /**
* The invoice number of the transaction.
*/
 public String InvoiceNumber;
 /**
* Whether to perform an authorize only transaction (true) or to
* capture/settle the transaction (false).
*
* If true the ProcessCard field is ignored.
*/
 public boolean AuthOnly;

 /**
* Whether to capture/settle the transaction.
*
* If AuthOnly is true this field is ignored.
*/
 public boolean ProcessCard;

 /**
* Whether to always store the card information.
*
* This is ignored if the OnlyStoreCardOnSuccessfulProcess field is true.
*/
 public boolean StoreCard;

 /**
* Whether to save the tokenized card only if the card transaction succeeds.
*/
 public boolean OnlyStoreCardOnSuccessfulProcess;

 /**
* Indicates if the 'CardHolderName' section should be required, optional,
* or hidden.
*/
 public RequirementType CardHolderNameRequirementType;

 /**
* Indicates if the 'SecurityCode' section should be required, optional, or
* hidden.
*/
 public RequirementType SecurityCodeRequirementType;

 /**
* Indicates if the 'AVS' section should be required, optional, or hidden.
*/
 public RequirementType AvsRequirementType;

 /**
* The URL to use for the CSS that drives the look of the page (max 1024
* characters).
*/
 public String CssUrl;
}

// -------------------------------------------------------------------------------------------- //
// Result.java

/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

/**
 * The result of the call.
 */
public class Result {
 /**
* The result of the transaction
*
* Will always be SUCCESS or FAILURE
*/
 public String ResultValue;

 /**
* The result code of the transaction
*
*
* Will be a two-digit string with only numbers. Allows "00" as a response.
*/
 public String ResultCode;

 /**
* The English-text message of what went wrong (if anything)
*
*
* The documentation shows the empty string being returned in the success
* cases.
*/
 public String ResultMessage;
}

// -------------------------------------------------------------------------------------------- //
// CreateHostedTransactionResponse.java

/*
ProPay provides the following code "AS IS."
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/

public class CreateHostedTransactionResponse {
 /**
* The API Result from the method call.
*/
 public Result Result;

 /**
* The identifier used to get the results of the hosted transaction after it
* is completed.
*/
 public String HostedTransactionIdentifier;
}

Response Handling

The following sample uses the Unirest and Jackson libraries.

You can add them to your project using:

Apache Maven
<dependency>
<groupId>com.mashape.unirest</groupId>
<artifactId>unirest-java</artifactId>
<version>1.4.9</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.8.8.1</version>
</dependency>


Gradle/Grails
compile 'com.mashape.unirest:unirest-java:1.4.9'
compile 'com.fasterxml.jackson.core:jackson-databind:2.8.8.1'

Request Submission

Response Handling

Request Values

Request Element

Type

Max

Required

Notes

AuthenticationToken

String

100

Authorization

Valid value is a GUID. Value supplied by ProPay. Used to access the API

BillerAccountId

String

16

Authorization

Value supplied by ProPay. Used to identify the correct collection of tokens.

Amount

Integer

 

Required

The value representing the number of pennies in USD, or the number of [currency] without decimals.

AcceptMasterPass

Boolean

 

Optional

Valid values are:
true
False

User can use MasterPass making CreateHostedTransactionIdentifier call with AcceptmasterPass true .This property is ignored if merchant is not subscribed for Masterpass. 

AvsRequirementType

Integer

1

Required

Indicates if the 'AVS' section should be required, optional, or hidden.
1=AVS Required
2=AVS Displayed but Optional
3=Hidden

BillerAccountId

String

-

Optional

Intended Future Use

BillerAuthToken

String

-

Optional

Intended Future Use

BillerIdentityId

Long

-

Optional

Intended Future Use

CardHolderNameRequirementType

Integer

1

Required

Indicates if the 'CardHolderName' section should be required, optional, or hidden.
1=CH Name Displayed, Required
2=CH Name Displayed, Optional
3=CH Name Hidden

 

Comment1

String

128

Optional

Comment 1 to be displayed to the user on the Hosted Page.

Comment2

String

128

Optional

Comment 2 to be displayed to the user on the Hosted Page.

CreationDate

DateTime

-

 

 

CssUrl

String

1024

Optional

The fully qualified URL to use for the CSS that drives the look of the page.

Must be hosted over https
Sending empty value removes all default styles

CurrencyCode

String

3

Required

ISO 4217 standard 3 character currency code.

Frauddetectors

Object

-

Optional

Please See ProtectPay Appendix for details concerning the FrauddetectorsObject

Frauddetectorss.FrauddetectorProviderName

String

 

Required*

If using Frauddetectors Object this Element is required.

HostedTransactionIdentifier

String

-

 

The hosted transaction ID (GUID) that was returned from the call to "CreateHostedTransactionIdentifier"

InvoiceNumber

String

50

Optional

Highly recommended. Transaction descriptor-only passed if supported by the gateway.

MerchantProfileId

Long

-

Required

Used to specify which processor and merchant account to process the transaction against.

OnlyStoreCardOnSuccessfulProcess

Boolean

-

Required

Valid values are:
true

false

Only stored the card information if the card transaction was successful.

* This is ignored if the "StoreCard" property is set to true

PaymentTypeId

String

1

Required

Valid Values are
0=credit card
1=ach

If set to 1 overrides display options and displays Name and ACH field only

PayerId

 

Long

16

Required

The Payer under which the PaymentMethodId should be created under.

ProcessCard

Boolean

-

Required*

Valid values are:
true
false

Process (authorize and capture) the card transaction. This property is ignored if the "AuthOnly" property is true.

Protected

Boolean

5

Optional

Valid values are:
true
false

Payment methods set to ‘true’ cannot be deleted by a payer.

ReturnURL

String

1024

Optional

The fully qualified URL to redirect once transaction is completed.

* Sending an empty value will not allow to perform a transaction.

SecurityCodeRequirementType

Integer

1

Required

Indicates if the 'SecurityCode' section should be required, optional, or hidden.
1=cvv displayed, required
2=cvv displayed, optional
3=cvv hidden

StoreCard

Boolean

 

Required*

Valid values are:
true
false

Always store the card information. This is ignored if the "OnlyStoreCardOnSuccessfulProcess" property is true.

If [AuthOnly], [ProcessCard] and [StoreCard] are set to False the hosted page will not do anything

 

Request values defined (Optional Elements to pre-load the Hosted Payment Page)

Request Element

Type

Max

Required

Notes

Address1

String

50

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Address 1 Field.

*Max length is 40 for multi-currency transactions.

Address2

String

50

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Address 2 Field.

*Max length is 40 for multi-currency transactions.

City

String

25

Optional

If this value is supplied the Hosted Payment Page will load with this value in the City Field

Country

String

3

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Country Field

*Must be ISO 3166 standard 3 character country code.

Description

String

100

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Description Field

Name

String

3

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Name Field

State

String

20*

Optional

If this value is supplied the Hosted Payment Page will load with this value in the State Field

Country Code is Required if preloading the State Selection Box

Limited to USA/CAN only

ZipCode

String

10

Optional

If this value is supplied the Hosted Payment Page will load with this value in the Postal Code Field

Response Values

Response Element

Type

Notes

RequestResult.ResultValue

String

The ProtectPay API Method Response Value;

SUCCESS indicates the method completed;

FAILURE indicates the method call failed and the reason is indicated in the ResultCode and ResultMessage

RequestResult.ResultCode

String

The ProtectPay API Method Response Code. See Appendix for possible returned Values

RequestResult.ResultMessage

String

The ProtectPay API Method Response Message. See Appendix for possible returned Messages

HostedTransactionIdentifier

String

Unique One Time use only identifier for a Hosted Transaction Page