ProtectPay – Process with an Existing Token

A ProtectPay® Payer Management Interface, such as the HPP, is recommended when credit card information must be obtained, for the first time, from one of your customers. ProtectPay® also supports cases where the merchant already has a valid ProtectPay® token.
  • Recurring payments/recurring billing
  • Automatic shipments
  • Cards maintained 'on file' for a more convenient shopping experience
Use the ProtectPay® API call, ProcessPaymentMethodTransaction to initiate a credit card transaction when you already have a ProtectPay® payment method ID available.

Client validation of credit cards
Before processing or tokenizing a credit card that will be processed against any ProPay API, you should consider client-side validation of its card number. Any validation that you do should occur on the cardholder’s browser using JavaScript or similar technology, and should consider what a valid card number looks like:
  • Card numbers should be of an appropriate length. Remember, length-format can differ by card-brand even though 16 digits is most common.
  • Card numbers usually begin with a specific digit that is based on the brand. Just remember: MasterCard cards might also begin with a 2.
  • Card numbers always pass a LUHN check
How to call this method?

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

Example Response

{
 PaymentMethodId: "deabf6cf-7325-4547-83e0-54ebeb06eeb4",
 IsRecurringPayment: false,
 CreditCardOverrides: {
FullName: "Test User", 
ExpirationDate: "1014", 
CVV: "999", 
Billing: { 
Address1: "3400 N Ashton Blvd",
Address2: "Suite 200",
Address3: "",
City: "Lehi",
State: "UT",
ZipCode: "84043",
Country: "USA",
TelephoneNumber: "8012223333",
Email: "test@user.com"

 },
 AchOverrides: null,
 PayerOverrides: {
IpAddress: "127.0.0.1" 
 },
 MerchantProfileId: 1234,
 PayerAccountId: "5823760912097888",
 Amount: 300,
 CurrencyCode: "USD",
 Invoice: "7e9e6542-febb-4883-95ec-956d305e0143",
 Comment1: "Credit Comment 1",
 Comment2: "Credit Comment 2",
 IsDebtRepayment: "true"
}

{
"Transaction": {
"AVSCode": "T",
"AuthorizationCode": "A11111",
"CurrencyConversionRate": 1,
"CurrencyConvertedAmount": 300,
"CurrencyConvertedCurrencyCode": "USD",
"ResultCode": {
"ResultValue": "SUCCESS",
"ResultCode": "00",
"ResultMessage": ""
},
"TransactionHistoryId": "12040092",
"TransactionId": "13",
"TransactionResult": "Success",
"CVVResponseCode": "M",
"GrossAmt": 300,
"NetAmt": 254,
"PerTransFee": 35,
"Rate": 3.5,
"GrossAmtLessNetAmt": 46
},
"RequestResult": {
"ResultValue": "SUCCESS",
"ResultCode": "00",
"ResultMessage": ""
}
}

Implementation Details
Request Submission

namespace ProtectPayApi_ProcessPaymentMethod
{
using System;
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 ProcessPaymentMethodProgram
{
public static void Main(string[] args)
{
var processPaymentMethodResponse = ProcessPaymentMethod();
}
private static ProcessPaymentMethodTransactionResponse ProcessPaymentMethod()
{
var baseUrl = "https://xmltestapi.propay.com/ProtectPay";
var request = BuildRequest();
var pathAndQuery = string.Format("/Payers/{0}/PaymentMethods/ProcessedTransactions/", request.PayerAccountId);
var restRequest = CreateRestRequest(pathAndQuery, RestSharp.Method.PUT);
restRequest.AddBody(request);
return Execute<ProcessPaymentMethodTransactionResponse>(restRequest, baseUrl);
}

private static ProcessPaymentMethodTransactionRequest BuildRequest()
{
// validated against API documenation
return new ProcessPaymentMethodTransactionRequest
{
Amount = 500,
CurrencyCode = "USD",
MerchantProfileId = "0",
PayerAccountId = "3702457414469838",
PaymentMethodId = "411879be-1011-4ee3-8382-3598007769df,"
};
}

/// <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 "ProcessPaymentMethodTransaction" method.
/// </summary>
public class ProcessPaymentMethodTransactionRequest
{
/// <summary>
/// Gets or sets the payment method id.
/// </summary>
public string PaymentMethodId { get; set; }

/// <summary>
/// Gets or sets a value indicating whether the transaction is a recurring payment.
/// </summary>
public bool IsRecurringPayment { get; set; }

/// <summary>
/// Gets or sets the credit card Override values.
/// </summary>
public CreditCardOverrides CreditCardOverrides { get; set; }

/// <summary>
/// Gets or sets the ACH override values.
/// </summary>
public AchOverrides AchOverrides { get; set; }

/// <summary>
/// Gets or sets the payer override values.
/// </summary>
public PayerOverrides PayerOverrides { get; set; }
/// <summary>
/// Gets or sets the ID of the merchant profile to use for this transaction.
/// </summary>
/// <remarks>
/// <para>Optional </para>
/// Any 64-bit signed integer.
/// If zero (default) is specified, the "default" merchant profile for the identity will be used.
/// </remarks>
public string MerchantProfileId { get; set; }

/// <summary>
/// REQUIRED: Gets or sets the payer's account id.
/// </summary>
public string PayerAccountId { get; set; }

/// <summary>
/// REQUIRED: Gets or sets amount of the transaction.
/// </summary>
/// <remarks>
/// <para>Amounts should be integers. No decimals are allowed.</para>
/// </remarks>
/// <example>
/// <para>$ 0.50 = 50</para>
/// <para>$ 1.50 = 150</para>
/// <para>$100.00 = 10000</para>
/// </example>
public int Amount { get; set; }

/// <summary>
/// REQUIRED: Gets or sets the currency code for the transaction.
/// </summary>
/// <remarks>
/// ISO 3166-1 3 digit country codes
/// </remarks>
/// <example>
/// <para>840 - United States of America</para>
/// <para>124 - Canada</para>
/// </example>
public string CurrencyCode { get; set; }

/// <summary>
/// Gets or sets the Invoice number for the transaction.
/// </summary>
/// <remarks>
/// <para>Optional </para>
/// <para>Length : 50</para>
/// </remarks>
public string Invoice { get; set; }

/// <summary>
/// Get or sets the comment 1.
/// </summary>
/// <remarks>
/// <para>Optional </para>
/// <para>Length : 128</para>
/// </remarks>
public string Comment1 { get; set; }

/// <summary>
/// Gets or sets the comment 2.
/// </summary>
/// <remarks>
/// <para>Optional </para>
/// <para>Length : 128</para>
/// </remarks>
public string Comment2 { get; set; }

/// <summary>
/// Gets or sets the debt repayment indicator from the request.
/// </summary>
public bool IsDebtRepayment { get; set; }
}

/// <summary>
/// Credit Card Overrides.
/// </summary>
public class CreditCardOverrides
{
/// <summary>
/// The Billing Address of the credit card.
/// </summary>
public Billing Billing
{
get; set;
}

/// <summary>
/// The expiration date of the credit card.
/// </summary>
public string ExpirationDate
{
get; set;
}

/// <summary>
/// The full name of the card holder.
/// </summary>
public string FullName
{
get; set;
}

/// <summary>
/// The CVV for the card.
/// </summary>
public string CVV
{
get; set;
}
}

/// <summary>
/// Payers billing information.
/// </summary>
public class Billing
{
/// <summary>
/// Address field 1.
/// </summary>
/// <remarks>
/// <para>Length : 50</para>
/// <para>Required</para>
/// </remarks>
public string Address1
{
get; set;
}

/// <summary>
/// Address field 2.
/// </summary>
/// <remarks>
/// <para>Length : 50</para>
/// <para>Optional</para>
/// </remarks>
public string Address2
{
get; set;
}

/// <summary>
/// Address field 3.
/// </summary>
/// <remarks>
/// <para>Length : 50</para>
/// <para>Optional</para>
/// </remarks>
public string Address3
{
get; set;
}

/// <summary>
/// City.
/// </summary>
/// <remarks>
/// <para>Length : 25</para>
/// <para>Required</para>
/// </remarks>
public string City
{
get; set;
}

/// <summary>
/// State or province.
/// </summary>
/// <remarks>
/// <para>Length : 2</para>
/// <para>Required</para>
/// </remarks>
/// <example>
/// <para>"UT" for Utah</para>
/// <para>"AB" for Alberta</para>
/// </example>
public string State
{
get; set;
}

/// <summary>
/// Zip or Postal Code.
/// </summary>
/// <remarks>
/// <para>Length : 10</para>
/// <para>Required</para>
/// </remarks>
/// <example>
/// <para>"84058" - Orem, Utah</para>
/// <para>"T1X 1E1" - Calgary, Alberta</para>
/// </example>
public string ZipCode
{
get; set;
}

/// <summary>
/// The country code.
/// </summary>
/// <remarks>
/// <para>Required</para>
/// <para>Note: See supported countries </para>
/// </remarks>
/// <example>
/// <para>840 = United States of America</para>
/// <para>124 = Canada</para>
/// </example>
public string Country
{
get; set;
}

/// <summary>
/// The telephone number.
/// </summary>
public string TelephoneNumber
{
get; set;
}

/// <summary>
/// The Email Address.
/// </summary>
public string Email
{
get; set;
}
}

/// <summary>
/// Overrides for ACH transactions.
/// </summary>
public class AchOverrides
{
/// <summary>
/// The bank account type for the transaction (leave blank to use the type on file).
/// </summary>
public string BankAccountType
{
get; set;
}

/// <summary>
/// The Standard Entry Class Code for the transaction.
/// </summary>
public string SecCode
{
get; set;
}
}

/// <summary>
/// Information about overrides pertaining to the payer.
/// </summary>
public class PayerOverrides
{
/// <summary>
/// The IP Address of the user performing the transaction.
/// </summary>
public string IpAddress
{
get; set;
}
}

/// <summary>
/// The value returned from a call to the "ProcessPaymentMethodTransaction" method.
/// </summary>
public class ProcessPaymentMethodTransactionResponse
{
/// <summary>
/// <c>TransactionInformation</c> object for each transaction that was processed.
/// </summary>
public TransactionInformation Transaction
{
get; set;
}

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

/// <summary>
/// Transaction information from a attempt at processing a payment method in the ProPay system.
/// </summary>
public class TransactionInformation
{
/// <summary>
/// Gets or sets transaction history id in the ProPay system.
/// </summary>
public string TransactionHistoryId { get; set; }

/// <summary>
/// Gets or sets authorization code from the system of record.
/// </summary>
public string AuthorizationCode { get; set; }

/// <summary>
/// Gets or sets address verification system (AVS) code.
/// </summary>
/// <remarks>
/// Only present if billing information is present on a payment method and
/// system of record supports AVS.
/// </remarks>
public string AVSCode { get; set; }

/// <summary>
/// Gets or sets the amount in the settled currency.
/// </summary>
public int CurrencyConvertedAmount { get; set; }

/// <summary>
/// Gets or sets the settled currency code.
/// </summary>
public string CurrencyConvertedCurrencyCode { get; set; }

/// <summary>
/// Gets or sets the conversion rate from the requested currency to the settled currency.
/// </summary>
public decimal CurrencyConversionRate { get; set; }

/// <summary>
/// Gets or sets gross amount in the settled currency.
/// </summary>
public virtual int? GrossAmt { get; set; }

/// <summary>
/// Gets or sets gross amount less net amount in the settled currency.
/// </summary>
public virtual int? GrossAmtLessNetAmt { get; set; }

/// <summary>
/// Gets or sets net amount in the settled currency.
/// </summary>
public virtual int? NetAmt { get; set; }

/// <summary>
/// Gets or sets per transaction fee in the settled currency.
/// </summary>
public virtual int? PerTransFee { get; set; }

/// <summary>
/// Gets or sets rate percentage.
/// </summary>
public virtual decimal? Rate { get; set; }

/// <summary>
/// Gets or sets specific result information from the transaction.
/// </summary>
public Result ResultCode { get; set; }

/// <summary>
/// Gets or sets transaction ID from the system of record.
/// </summary>
public string TransactionId { get; set; }

/// <summary>
/// <c>Gets or sets result</c> of the transaction.
/// </summary>
public string TransactionResult { 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 processing a payment method transaction */
private $_paymentMethodTransactionData;
private $_paymentMethodTransactionInfo;

/**
* @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;
}

/**
* @param array $paymentMethodTransactionData
* @return $this
*/
public function setPaymentMethodTransactionData($paymentMethodTransactionData) {
$this->_paymentMethodTransactionData = $paymentMethodTransactionData;
return $this;
}

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

/**
* @return $this
*/
public function processPaymentMethodTransaction($payerExternalAccountId) {
$data_string = json_encode($this->_paymentMethodTransactionData);

$ch = curl_init($this->_apiBaseUrl . '/protectpay/Payers/' . $payerExternalAccountId . '/PaymentMethods/AuthorizedTransactions');
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->_paymentMethodTransactionInfo = curl_exec($ch);
return $this;
}
}

$data = [
"PaymentMethodId" => "06f97670-48c2-4679-93fc-d61771d410f9",
"IsRecurringPayment" => false,

"CreditCardOverrides" =>
[
"FullName" => "Test User",
"ExpirationDate" => "1014",
"CVV" => "999",
"Billing" =>
[
"Address1" => "3400 N Ashton Blvd",
"Address2" => "Suite 200",
"Address3" => "",
"City" => "Lehi",
"State" => "UT",
"ZipCode" => "84043",
"Country" => "USA",
"TelephoneNumber" => "8012223333",
"Email" => "test@user.com"
]
],
"AchOverrides" => null,
"PayerOverrides" =>
[
"IpAddress" => "127.0.0.1"
],
"MerchantProfileId" => "3351",
"PayerAccountId" => "999957370851397",
"Amount" => 300,
"CurrencyCode" => "USD",
"Invoice" => "Test Invoice",
"Comment1" => "Authorize Comment 1",
"Comment2" => "Authorize Comment 2",
"IsDebtRepayment" => "true"
];

// Process a payment method
$protectPayAPI = new ProtectPayApi();
$result = $protectPayAPI->setBillerId('9999986379225246')
->setAuthToken('16dfe8d7-889b-4380-925f-9c2c6ea4d930')
->setPaymentMethodTransactionData($data)
->processPaymentMethodTransaction('9999957370851397')
->getPaymentMethodTransactionInfo();

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 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 ProcessPaymentMethodSample {
 /**
* This URL would normally come from some configuration file or database.
*/
 String baseUrl = "https://xmltestapi.propay.com/protectpay";

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

ProcessPaymentMethodSample program = new ProcessPaymentMethodSample();

ProcessPaymentMethodTransactionResponse response = program.processPaymentMethodTransaction();

Result requestResult = response.RequestResult;

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

Transaction transactionDetail = response.Transaction;

if (transactionDetail != null) {
Result transactionResult = transactionDetail.ResultCode;
System.out.println("Transaction Result: " + transactionResult.ResultValue);
System.out.println("Transaction Result code: " + transactionResult.ResultCode);

System.out.println("Transaction History Id: " + transactionDetail.TransactionHistoryId);
System.out.println("Authorization Code: " + transactionDetail.AuthorizationCode);
System.out.println("AVS Code: " + transactionDetail.AvsCode);
System.out.println("Currency Converted Amount: " + transactionDetail.CurrencyConvertedAmount);
System.out.println("Currency Converted Currency Code: " + transactionDetail.CurrencyConvertedCurrencyCode);
System.out.println("Currency Conversion Rate: " + transactionDetail.CurrencyConversionRate);
System.out.println("Gross Amount: " + transactionDetail.GrossAmount);
System.out.println("Gross Amount Less Net Amount: " + transactionDetail.GrossAmountLessNetAmount);
System.out.println("Net Amount: " + transactionDetail.NetAmount);
System.out.println("Per Transaction Fee: " + transactionDetail.PerTransactionFee);
System.out.println("Rate: " + transactionDetail.Rate);
System.out.println("Transaction Id: " + transactionDetail.TransactionId);
System.out.println("Transaction Result: " + transactionDetail.TransactionResult);
}
 }

 /**
* Creates a payment method.
*
* @return The payment method response.
*/
 private ProcessPaymentMethodTransactionResponse processPaymentMethodTransaction() {

ProcessPaymentMethodTransaction paymentMethodTransaction = this.buildRequest();

String resourceUrl = this.getUrl(paymentMethodTransaction);

HttpRequestWithBody request = this.createRequest(baseUrl + resourceUrl);

request.body(paymentMethodTransaction);

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

 /**
* Gets the authentication token. This would normally be in a configuration
* file or database.
*
* @return The authentication token.
*/
 private String getAuthToken() {
return "16dfe8d7-889b-4380-925f-9c2c6ea4d930";
 }

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

 /**
* 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 String getPayerAccountId() {
return "6192936083671743";
 }

 /**
* Gets the payment method id.
*
* This would normally be in a database or generated as a result of an
* earlier call, see ProtectPay API Manual section "Create a
* PaymentMethodId" or "Payer Management Interface Methods"
*/
 private String getPaymentMethodId() {
return "dc74a8a3-35c1-40bc-9abb-096a3c397fa4";
 }

 /**
* 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;
 }

 /**
* Builds the request data.
*
* @returns The request data.
*/
 private ProcessPaymentMethodTransaction buildRequest() {
String payerAccountId = this.getPayerAccountId();
String paymentMethodId = this.getPaymentMethodId();

final int TenUsDollars = 1000;

ProcessPaymentMethodTransaction processPaymentMethodTransaction = new ProcessPaymentMethodTransaction();
processPaymentMethodTransaction.PayerAccountId = payerAccountId;
processPaymentMethodTransaction.PaymentMethodId = paymentMethodId;
processPaymentMethodTransaction.Amount = TenUsDollars;
processPaymentMethodTransaction.CurrencyCode = "USD";
processPaymentMethodTransaction.IsRecurringPayment = false;

return processPaymentMethodTransaction;
 }

 /**
* Gets the proper token URL for the given request.
*
* @returns The URL to be added to the base URL.
*/
 private String getUrl(ProcessPaymentMethodTransaction paymentMethodTransaction) {
String payerId = paymentMethodTransaction.PayerAccountId;

return "/Payers/" + payerId + "/PaymentMethods/ProcessedTransactions/";
 }

 /**
* 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

// ProcessPaymentMethodTransaction.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.
*/

/**
 * Data for processing a tokenized payment method.
 *
 * This example only shows required fields. See the ProtectPay API Manual under
 * "Process a PaymentMethodId" for additional optional fields.
 */
public class ProcessPaymentMethodTransaction {
 /**
* A flag indicating whether this payment is recurring, i.e. repeats on a
* scheduled basis.
*/
 public boolean IsRecurringPayment;

 /**
* The id of the tokenized payment method to process.
*/
 public String PaymentMethodId;

 /**
* The amount to charge in pennies (USD) or smallest unit of currency
* (non-USD) without decimals.
*
* e.g. $1.00 USD is 100 ¥10 JPY is 10 since Japanese Yen does not use a
* decimal place.
*/
 public int Amount;

 /**
* The 3 character currency code (see
* https://en.wikipedia.org/wiki/ISO_4217)
*/
 public String CurrencyCode;

 /**
* The id of the merchant processing profile to use.
*
* Important if the account has multiple processing gateways, e.g. for
* different countries.
*
*/
 public int MerchantProfileId;

 /**
* The account id of the payer that has the payment method.
*/
 public String PayerAccountId;
}

// -------------------------------------------------------------------------------------------- //
// 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;
}

// -------------------------------------------------------------------------------------------- //
// Transaction.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.
*/

import java.math.BigDecimal;

import com.fasterxml.jackson.annotation.JsonProperty;

/**
 * Transaction details.
 *
 */
public class Transaction {
 /**
* The transaction history id in the ProPay system.
*/
 public String TransactionHistoryId;

 /**
* The transaction authorization code from the issuing bank.
*/
 public String AuthorizationCode;

 /**
* The address verification system (AVS) code.
*
* Only present if billing information is present on payment method, or in
* the request.
*/
 @JsonProperty("AVSCode")
 public String AvsCode;

 /**
* The card verification value (CVV) response code.
*/
 @JsonProperty("CVVResponseCode")
 public String CvvResponseCode;

 /**
* The amount in the settled currency.
*/
 public int CurrencyConvertedAmount;

 /**
* The settled currency code.
*/
 public String CurrencyConvertedCurrencyCode;

 /**
* The conversion rate from the requested currency to the settled currency.
* e.g. USD to USD = 1, JPY to USD = 0.0090 (as of 5/17/2017)
*/
 public BigDecimal CurrencyConversionRate;

 /**
* The gross amount in the settled currency.
*/
 @JsonProperty("GrossAmt")
 public Integer GrossAmount;

 /**
* The gross amount less net amount in the settled currency.
*/
 @JsonProperty("GrossAmtLessNetAmt")
 public Integer GrossAmountLessNetAmount;

 /**
* The net amount in the settled currency.
*/
 @JsonProperty("NetAmt")
 public Integer NetAmount;

 /**
* The per transaction fee in the settled currency.
*/
 @JsonProperty("PerTransFee")
 public Integer PerTransactionFee;

 /**
* The percentage fee, if any.
*/
 public BigDecimal Rate;

 /**
* Result information from the transaction.
*/
 public Result ResultCode;

 /**
* The transaction number assigned by the processor.
*/
 public String TransactionId;

 /**
* The transaction result as reported by the processor.
*/
 public String TransactionResult;
}

// -------------------------------------------------------------------------------------------- //
// ProcessPaymentMethodTransactionResponse.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 value returned from call to process a payment method.
 *
 */
public class ProcessPaymentMethodTransactionResponse {
 /**
* The transaction details
*/
 public Transaction Transaction;

 /**
* The result of the request.
*/
 public Result RequestResult;
}

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.

IsRecurringPayment

Boolean

5

Required*

REST ONLY

Valid values are:
true
False

 

If set to false this transaction will not be marked recurring at the issuer

AchOverrides

Object

-

ACH Only

Used to override the information stored with the ACH PaymentMethodId type

AchOverrides.BankAccountType

String

1

Optional

Valid values are:
Checking
Savings
LoanCredit
GeneralLedger
SEPA (only used with specific gateways)

AchOverrides.MandateDate

DateTime

 yyyy-MM-dd

Optional*

*If SEPA then value is required.

AchOverrides.MandateDateSigned

DateTime

 yyyy-MM-dd

Optional*

*If SEPA then value is required.

AchOverrides.MandateId

String

3

Optional*

*If SEPA then value is required.

AchOverrides.SecCode

String

3

Required*

Standard Entry Class Code.  Valid values are:
PPD
CCD
WEB
TEL

 

*If the PaymentMethodId type is an ACH type this value is required

CreditCardOverrides

Object

-

Optional

Used to override the information stored with the credit card PaymentMethodId type

CreditCardOverrides.Billing

Object

-

Optional

Used to override the Billing information stored with the credit card PaymentMethodId type

CreditCardOverrides.Billing.Address1

String

50

Optional

Used to override the Address1 stored with the PaymentMethodId.

*Max length is 40 for multi-currency transactions.

CreditCardOverrides.Billing.Address2

String

50

Optional

Used to override the Address2 stored with the PaymentMethodId.

*Max length is 40 for multi-currency transactions.

CreditCardOverrides.Billing.Address3

String

50

Optional

Used to override the Address3 stored with the PaymentMethodId.

*Max length is 40 for multi-currency transactions.

CreditCardOverrides.Billing.City

String

25

Optional

Used to override the City stored with the PaymentMethodId

CreditCardOverrides.Billing.Country

String

3

Optional

Used to override the Country stored with the PaymentMethodId

*Must be ISO 3166 standard 3 character country code.

CreditCardOverrides.Billing.Email

String

100

Optional

Used to override the Email address stored with the PaymentMethodId

CreditCardOverrides.Billing.State

String

3

Optional

Used to override the State stored with the PaymentMethodId

CreditCardOverrides.Billing.TelephoneNumber

Integer

20*

Optional

Used to override the Telephone Number stored with the PaymentMethodId

*10 digits for US numbers.

CreditCardOverrides.Billing.ZipCode

String

10

Optional

Used to override the ZipCode stored with the PaymentMethodId

CreditCardOverrides.CVV

String

4

Optional

CVV code.

If submitting the CVV code with this transaction request it must be passed in the CreditCardOverrides Object

*ProtectPay will not store this value.

CreditCardOverrides.ExpirationDate

String

4

Optional

Used to override the Expiration Date stored with the PaymentMethodId

For a credit card these are submitted as 4 digit numeric values MMYY.

*Required if the Processor Gateway Requires an Expiration Date

CreditCardOverrides.FullName

String

50

Optional

Used to override the Account Name stored with the PaymentMethodId

PayerOverrides

Object

-

Optional

 

PayerOverrides.IpAddress

String

15

Optional

IP address as read from cardholder browser session.

paymentMethodID

GUID

36

Required

This is the ProtectPay ID for the Payment Method, also called a Token

The Payment Method Created Belongs to the PayerId it was Created For

Transaction

Object

-

Required

Contains Transaction Information

*REST passes the transaction values directly and not nested.

Transaction .Amount

Integer

 

Required

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

Transaction.Comment1

String

128

Optional

Transaction descriptor. Only passed if supported by the gateway.

Transaction.Comment2

String

128

Optional

Transaction descriptor. Only passed if supported by the gateway.

Transaction.CurrencyCode

String

3

Required

ISO 4217 standard 3 character currency code.

Transaction.Invoice

String

50

Optional

Recommended. Transaction descriptor-only passed if supported by the gateway.

*ProPay gateway rejects duplicates for same invoice #, card # and amount in 1 minute.

Transaction.IsDebtRepayment

Boolean

5

Optional

Valid Values are:
True
False

 

Only applicable for LegacyProPay and LegacyProPayCan gateways

Defaults to False if not submitted

Transaction.MerchantProfileId

Int(64)

Signed Int(64)

Required

The MerchantProfileId that was created using the supplied credentials for the supplied Gateway that is used to process against this particular gateway

Transaction.PayerAccountId

String

16

Required

This is the ProtectPay ID for the Payer Created and belongs to the BillerID that created it

Transaction.Frauddetectors

Object

-

Optional

Please See ProtectPay Appendix for details concerning the FraudDetectosrObject

Frauddetectorss.FrauddetectorProviderName

String

 

Required*

If using Frauddetectors Object this Element is required.

Response Values

Response Element

Type

Notes

RequestResult.ResultValue

String

The 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 Method Response Code. See ProtectPay Appendix A for possible returned values

RequestResult.ResultMessage

String

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

Transaction.AuthorizationCode

String

The auth code supplied by the issuing bank. *Only returned on a successful transaction

Transaction.AVSCode

String

AVS response produced by gateway. *Only returned if AVS information is supplied and AVS is supported by the gateway.

Transaction.CurrencyConversionRate

Decimal

The rate for currency conversion used for multi-currency transactions

Transaction.CurrencyConvertedAmount

Integer

Gross converted amount of transaction in the number of [currency] without decimals for multi-currency transactions

Transaction.CurrencyConvertedCurrencyCode

String

The currency the transaction was converted to for multi-currency transactions

Transaction.CVVResponseCode

String

 

Transaction.GrossAmt

Integer

Gross amount of transaction of pennies in USD, or the number of [currency] without decimals.

Not returned for ACH payment transactions.

Transaction.GrossAmtLessNetAmt

Integer

Total amount of fees charged; *ProPay Gateway Only. Not returned for ACH payment transactions.

Transaction.NetAmt

Integer

Net amount of transaction after fees charged; *ProPay Gateway Only. Not returned for ACH payment transactions.

Transaction.PerTransFee

Integer

Per transaction fee; *ProPay Gateway Only. Not returned for ACH payment transactions.

Transaction.Rate

Decimal

Percentage fee; *ProPay Gateway Only. Not returned for ACH payment transactions.

Transaction.ResultCode.ResultCode

String

The result code of the transaction request as reported by ProtectPay. See ProtectPay Appendix A for possible returned values.

Transaction.ResultCode.ResultMessage

String

The result message of the transaction request as reported by ProtectPay. See ProtectPay Appendix A for possible returned values

Transaction.ResultCode.ResultValue

String

The result value of the transaction request as reported by the ProtectPay. SUCCESS or FAILURE

Transaction.TransactionHistoryId

String

Unique transaction number assigned by ProtectPay.

Transaction.TransactionId

String

Transaction number assigned by processor (Gateway)

Transaction.TransactionResult

String

Transaction result as reported by processor (Gateway)

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}     ProcessPaymentMethodTransaction
{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.FraudDetection" xmlns:prop1="http://schemas.datacontract.org/2004/07/Propay.Contracts.SPS.External">
<soapenv:Header/>
<soapenv:Body>
<con:ProcessPaymentMethodTransaction>
<con:id>
<typ:AuthenticationToken>MyAuthToken</typ:AuthenticationToken>
<typ:BillerAccountId>MyBillerId</typ:BillerAccountId>
</con:id>
<con:transaction>
<typ:Amount>300</typ:Amount>
<typ:Comment1>Process Comment 1</typ:Comment1>
<typ:Comment2>Process Comment 2</typ:Comment2>
<typ:CurrencyCode>USD</typ:CurrencyCode>
<typ:Invoice>Invoice1</typ:Invoice>
<typ:IsDebtRepayment>false</typ:IsDebtRepayment>
<typ:MerchantProfileId>1234</typ:MerchantProfileId>
<typ:PayerAccountId>5823760912097888</typ:PayerAccountId>
</con:transaction>
<con:paymentMethodID>de1ae2bd-c194-437c-ba9a-cb0730bd92d1</con:paymentMethodID>
<con:optionalPaymentInfoOverrides>
<prop1:Ach>
<prop1:BankAccountType></prop1:BankAccountType>
<prop1:SecCode></prop1:SecCode>
</prop1:Ach>
<prop1:CreditCard>
<prop1:Billing>
<typ:Address1>3400 N Ashton Blvd</typ:Address1>
<typ:Address2>Suite 200</typ:Address2>
<typ:Address3></typ:Address3>
<typ:City>Lehi</typ:City>
<typ:Country>USA</typ:Country>
<typ:State>UT</typ:State>
<typ:TelephoneNumber>8665730951</typ:TelephoneNumber>
<typ:ZipCode>84043</typ:ZipCode>
</prop1:Billing>
<prop1:CVV>999</prop1:CVV> <prop1:ExpirationDate>0122</prop1:ExpirationDate>
<prop1:FullName>John Doe</prop1:FullName>
</prop1:CreditCard>
<prop1:Payer>
<prop1:IpAddress>0.0.0.0</prop1:IpAddress>
</prop1:Payer>
</con:optionalPaymentInfoOverrides>
</con:ProcessPaymentMethodTransaction>
</soapenv:Body>
</soapenv:Envelope>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ProcessPaymentMethodTransactionResponse xmlns="http://propay.com/SPS/contracts">
<ProcessPaymentMethodTransactionResult xmlns:a="http://propay.com/SPS/types" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:RequestResult>
<a:ResultCode>00</a:ResultCode>
<a:ResultMessage/>
<a:ResultValue>SUCCESS</a:ResultValue>
</a:RequestResult>
<a:Transaction>
<a:AVSCode>T</a:AVSCode>
<a:AuthorizationCode>A11111</a:AuthorizationCode>
<a:CurrencyConversionRate>1</a:CurrencyConversionRate>
<a:CurrencyConvertedAmount>300</a:CurrencyConvertedAmount>
<a:CurrencyConvertedCurrencyCode>USD</a:CurrencyConvertedCurrencyCode>
<a:ResultCode>
<a:ResultCode>00</a:ResultCode>
<a:ResultMessage/>
<a:ResultValue>SUCCESS</a:ResultValue>
</a:ResultCode>
<a:TransactionHistoryId>8392130</a:TransactionHistoryId>
<a:TransactionId>387</a:TransactionId>
<a:TransactionResult>Success</a:TransactionResult>
<a:CVVResponseCode>M</a:CVVResponseCode>
<a:GrossAmt>300</a:GrossAmt>
<a:NetAmt>267</a:NetAmt>
<a:PerTransFee>25</a:PerTransFee>
<a:Rate>2.69</a:Rate>
<a:GrossAmtLessNetAmt>33</a:GrossAmtLessNetAmt>
</a:Transaction>
</ProcessPaymentMethodTransactionResult>
</ProcessPaymentMethodTransactionResponse>
</s:Body>
</s:Envelope>
Implementation Details
Request Submission

namespace ProtectPayApi_ProcessPaymentMethod
{
using System;
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 ProcessPaymentMethodProgram
{
public static void Main(string[] args)
{
var processPaymentMethodResponse = ProcessPaymentMethod();
}
private static ProcessPaymentMethodTransactionResponse ProcessPaymentMethod()
{
var baseUrl = "https://xmltestapi.propay.com/ProtectPay";
var request = BuildRequest();
var pathAndQuery = string.Format("/Payers/{0}/PaymentMethods/ProcessedTransactions/", request.PayerAccountId);
var restRequest = CreateRestRequest(pathAndQuery, RestSharp.Method.PUT);
restRequest.AddBody(request);
return Execute<ProcessPaymentMethodTransactionResponse>(restRequest, baseUrl);
}

private static ProcessPaymentMethodTransactionRequest BuildRequest()
{
// validated against API documenation
return new ProcessPaymentMethodTransactionRequest
{
Amount = 500,
CurrencyCode = "USD",
MerchantProfileId = "0",
PayerAccountId = "3702457414469838",
PaymentMethodId = "411879be-1011-4ee3-8382-3598007769df,"
};
}

/// <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 "ProcessPaymentMethodTransaction" method.
/// </summary>
public class ProcessPaymentMethodTransactionRequest
{
/// <summary>
/// Gets or sets the payment method id.
/// </summary>
public string PaymentMethodId { get; set; }

/// <summary>
/// Gets or sets a value indicating whether the transaction is a recurring payment.
/// </summary>
public bool IsRecurringPayment { get; set; }

/// <summary>
/// Gets or sets the credit card Override values.
/// </summary>
public CreditCardOverrides CreditCardOverrides { get; set; }

/// <summary>
/// Gets or sets the ACH override values.
/// </summary>
public AchOverrides AchOverrides { get; set; }

/// <summary>
/// Gets or sets the payer override values.
/// </summary>
public PayerOverrides PayerOverrides { get; set; }
/// <summary>
/// Gets or sets the ID of the merchant profile to use for this transaction.
/// </summary>
/// <remarks>
/// <para>Optional </para>
/// Any 64-bit signed integer.
/// If zero (default) is specified, the "default" merchant profile for the identity will be used.
/// </remarks>
public string MerchantProfileId { get; set; }

/// <summary>
/// REQUIRED: Gets or sets the payer's account id.
/// </summary>
public string PayerAccountId { get; set; }

/// <summary>
/// REQUIRED: Gets or sets amount of the transaction.
/// </summary>
/// <remarks>
/// <para>Amounts should be integers. No decimals are allowed.</para>
/// </remarks>
/// <example>
/// <para>$ 0.50 = 50</para>
/// <para>$ 1.50 = 150</para>
/// <para>$100.00 = 10000</para>
/// </example>
public int Amount { get; set; }

/// <summary>
/// REQUIRED: Gets or sets the currency code for the transaction.
/// </summary>
/// <remarks>
/// ISO 3166-1 3 digit country codes
/// </remarks>
/// <example>
/// <para>840 - United States of America</para>
/// <para>124 - Canada</para>
/// </example>
public string CurrencyCode { get; set; }

/// <summary>
/// Gets or sets the Invoice number for the transaction.
/// </summary>
/// <remarks>
/// <para>Optional </para>
/// <para>Length : 50</para>
/// </remarks>
public string Invoice { get; set; }

/// <summary>
/// Get or sets the comment 1.
/// </summary>
/// <remarks>
/// <para>Optional </para>
/// <para>Length : 128</para>
/// </remarks>
public string Comment1 { get; set; }

/// <summary>
/// Gets or sets the comment 2.
/// </summary>
/// <remarks>
/// <para>Optional </para>
/// <para>Length : 128</para>
/// </remarks>
public string Comment2 { get; set; }

/// <summary>
/// Gets or sets the debt repayment indicator from the request.
/// </summary>
public bool IsDebtRepayment { get; set; }
}

/// <summary>
/// Credit Card Overrides.
/// </summary>
public class CreditCardOverrides
{
/// <summary>
/// The Billing Address of the credit card.
/// </summary>
public Billing Billing
{
get; set;
}

/// <summary>
/// The expiration date of the credit card.
/// </summary>
public string ExpirationDate
{
get; set;
}

/// <summary>
/// The full name of the card holder.
/// </summary>
public string FullName
{
get; set;
}

/// <summary>
/// The CVV for the card.
/// </summary>
public string CVV
{
get; set;
}
}

/// <summary>
/// Payers billing information.
/// </summary>
public class Billing
{
/// <summary>
/// Address field 1.
/// </summary>
/// <remarks>
/// <para>Length : 50</para>
/// <para>Required</para>
/// </remarks>
public string Address1
{
get; set;
}

/// <summary>
/// Address field 2.
/// </summary>
/// <remarks>
/// <para>Length : 50</para>
/// <para>Optional</para>
/// </remarks>
public string Address2
{
get; set;
}

/// <summary>
/// Address field 3.
/// </summary>
/// <remarks>
/// <para>Length : 50</para>
/// <para>Optional</para>
/// </remarks>
public string Address3
{
get; set;
}

/// <summary>
/// City.
/// </summary>
/// <remarks>
/// <para>Length : 25</para>
/// <para>Required</para>
/// </remarks>
public string City
{
get; set;
}

/// <summary>
/// State or province.
/// </summary>
/// <remarks>
/// <para>Length : 2</para>
/// <para>Required</para>
/// </remarks>
/// <example>
/// <para>"UT" for Utah</para>
/// <para>"AB" for Alberta</para>
/// </example>
public string State
{
get; set;
}

/// <summary>
/// Zip or Postal Code.
/// </summary>
/// <remarks>
/// <para>Length : 10</para>
/// <para>Required</para>
/// </remarks>
/// <example>
/// <para>"84058" - Orem, Utah</para>
/// <para>"T1X 1E1" - Calgary, Alberta</para>
/// </example>
public string ZipCode
{
get; set;
}

/// <summary>
/// The country code.
/// </summary>
/// <remarks>
/// <para>Required</para>
/// <para>Note: See supported countries </para>
/// </remarks>
/// <example>
/// <para>840 = United States of America</para>
/// <para>124 = Canada</para>
/// </example>
public string Country
{
get; set;
}

/// <summary>
/// The telephone number.
/// </summary>
public string TelephoneNumber
{
get; set;
}

/// <summary>
/// The Email Address.
/// </summary>
public string Email
{
get; set;
}
}

/// <summary>
/// Overrides for ACH transactions.
/// </summary>
public class AchOverrides
{
/// <summary>
/// The bank account type for the transaction (leave blank to use the type on file).
/// </summary>
public string BankAccountType
{
get; set;
}

/// <summary>
/// The Standard Entry Class Code for the transaction.
/// </summary>
public string SecCode
{
get; set;
}
}

/// <summary>
/// Information about overrides pertaining to the payer.
/// </summary>
public class PayerOverrides
{
/// <summary>
/// The IP Address of the user performing the transaction.
/// </summary>
public string IpAddress
{
get; set;
}
}

/// <summary>
/// The value returned from a call to the "ProcessPaymentMethodTransaction" method.
/// </summary>
public class ProcessPaymentMethodTransactionResponse
{
/// <summary>
/// <c>TransactionInformation</c> object for each transaction that was processed.
/// </summary>
public TransactionInformation Transaction
{
get; set;
}

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

/// <summary>
/// Transaction information from a attempt at processing a payment method in the ProPay system.
/// </summary>
public class TransactionInformation
{
/// <summary>
/// Gets or sets transaction history id in the ProPay system.
/// </summary>
public string TransactionHistoryId { get; set; }

/// <summary>
/// Gets or sets authorization code from the system of record.
/// </summary>
public string AuthorizationCode { get; set; }

/// <summary>
/// Gets or sets address verification system (AVS) code.
/// </summary>
/// <remarks>
/// Only present if billing information is present on a payment method and
/// system of record supports AVS.
/// </remarks>
public string AVSCode { get; set; }

/// <summary>
/// Gets or sets the amount in the settled currency.
/// </summary>
public int CurrencyConvertedAmount { get; set; }

/// <summary>
/// Gets or sets the settled currency code.
/// </summary>
public string CurrencyConvertedCurrencyCode { get; set; }

/// <summary>
/// Gets or sets the conversion rate from the requested currency to the settled currency.
/// </summary>
public decimal CurrencyConversionRate { get; set; }

/// <summary>
/// Gets or sets gross amount in the settled currency.
/// </summary>
public virtual int? GrossAmt { get; set; }

/// <summary>
/// Gets or sets gross amount less net amount in the settled currency.
/// </summary>
public virtual int? GrossAmtLessNetAmt { get; set; }

/// <summary>
/// Gets or sets net amount in the settled currency.
/// </summary>
public virtual int? NetAmt { get; set; }

/// <summary>
/// Gets or sets per transaction fee in the settled currency.
/// </summary>
public virtual int? PerTransFee { get; set; }

/// <summary>
/// Gets or sets rate percentage.
/// </summary>
public virtual decimal? Rate { get; set; }

/// <summary>
/// Gets or sets specific result information from the transaction.
/// </summary>
public Result ResultCode { get; set; }

/// <summary>
/// Gets or sets transaction ID from the system of record.
/// </summary>
public string TransactionId { get; set; }

/// <summary>
/// <c>Gets or sets result</c> of the transaction.
/// </summary>
public string TransactionResult { 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 processing a payment method transaction */
private $_paymentMethodTransactionData;
private $_paymentMethodTransactionInfo;

/**
* @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;
}

/**
* @param array $paymentMethodTransactionData
* @return $this
*/
public function setPaymentMethodTransactionData($paymentMethodTransactionData) {
$this->_paymentMethodTransactionData = $paymentMethodTransactionData;
return $this;
}

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

/**
* @return $this
*/
public function processPaymentMethodTransaction($payerExternalAccountId) {
$data_string = json_encode($this->_paymentMethodTransactionData);

$ch = curl_init($this->_apiBaseUrl . '/protectpay/Payers/' . $payerExternalAccountId . '/PaymentMethods/AuthorizedTransactions');
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->_paymentMethodTransactionInfo = curl_exec($ch);
return $this;
}
}

$data = [
"PaymentMethodId" => "06f97670-48c2-4679-93fc-d61771d410f9",
"IsRecurringPayment" => false,

"CreditCardOverrides" =>
[
"FullName" => "Test User",
"ExpirationDate" => "1014",
"CVV" => "999",
"Billing" =>
[
"Address1" => "3400 N Ashton Blvd",
"Address2" => "Suite 200",
"Address3" => "",
"City" => "Lehi",
"State" => "UT",
"ZipCode" => "84043",
"Country" => "USA",
"TelephoneNumber" => "8012223333",
"Email" => "test@user.com"
]
],
"AchOverrides" => null,
"PayerOverrides" =>
[
"IpAddress" => "127.0.0.1"
],
"MerchantProfileId" => "3351",
"PayerAccountId" => "999957370851397",
"Amount" => 300,
"CurrencyCode" => "USD",
"Invoice" => "Test Invoice",
"Comment1" => "Authorize Comment 1",
"Comment2" => "Authorize Comment 2",
"IsDebtRepayment" => "true"
];

// Process a payment method
$protectPayAPI = new ProtectPayApi();
$result = $protectPayAPI->setBillerId('9999986379225246')
->setAuthToken('16dfe8d7-889b-4380-925f-9c2c6ea4d930')
->setPaymentMethodTransactionData($data)
->processPaymentMethodTransaction('9999957370851397')
->getPaymentMethodTransactionInfo();

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 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 ProcessPaymentMethodSample {
 /**
* This URL would normally come from some configuration file or database.
*/
 String baseUrl = "https://xmltestapi.propay.com/protectpay";

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

ProcessPaymentMethodSample program = new ProcessPaymentMethodSample();

ProcessPaymentMethodTransactionResponse response = program.processPaymentMethodTransaction();

Result requestResult = response.RequestResult;

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

Transaction transactionDetail = response.Transaction;

if (transactionDetail != null) {
Result transactionResult = transactionDetail.ResultCode;
System.out.println("Transaction Result: " + transactionResult.ResultValue);
System.out.println("Transaction Result code: " + transactionResult.ResultCode);

System.out.println("Transaction History Id: " + transactionDetail.TransactionHistoryId);
System.out.println("Authorization Code: " + transactionDetail.AuthorizationCode);
System.out.println("AVS Code: " + transactionDetail.AvsCode);
System.out.println("Currency Converted Amount: " + transactionDetail.CurrencyConvertedAmount);
System.out.println("Currency Converted Currency Code: " + transactionDetail.CurrencyConvertedCurrencyCode);
System.out.println("Currency Conversion Rate: " + transactionDetail.CurrencyConversionRate);
System.out.println("Gross Amount: " + transactionDetail.GrossAmount);
System.out.println("Gross Amount Less Net Amount: " + transactionDetail.GrossAmountLessNetAmount);
System.out.println("Net Amount: " + transactionDetail.NetAmount);
System.out.println("Per Transaction Fee: " + transactionDetail.PerTransactionFee);
System.out.println("Rate: " + transactionDetail.Rate);
System.out.println("Transaction Id: " + transactionDetail.TransactionId);
System.out.println("Transaction Result: " + transactionDetail.TransactionResult);
}
 }

 /**
* Creates a payment method.
*
* @return The payment method response.
*/
 private ProcessPaymentMethodTransactionResponse processPaymentMethodTransaction() {

ProcessPaymentMethodTransaction paymentMethodTransaction = this.buildRequest();

String resourceUrl = this.getUrl(paymentMethodTransaction);

HttpRequestWithBody request = this.createRequest(baseUrl + resourceUrl);

request.body(paymentMethodTransaction);

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

 /**
* Gets the authentication token. This would normally be in a configuration
* file or database.
*
* @return The authentication token.
*/
 private String getAuthToken() {
return "16dfe8d7-889b-4380-925f-9c2c6ea4d930";
 }

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

 /**
* 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 String getPayerAccountId() {
return "6192936083671743";
 }

 /**
* Gets the payment method id.
*
* This would normally be in a database or generated as a result of an
* earlier call, see ProtectPay API Manual section "Create a
* PaymentMethodId" or "Payer Management Interface Methods"
*/
 private String getPaymentMethodId() {
return "dc74a8a3-35c1-40bc-9abb-096a3c397fa4";
 }

 /**
* 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;
 }

 /**
* Builds the request data.
*
* @returns The request data.
*/
 private ProcessPaymentMethodTransaction buildRequest() {
String payerAccountId = this.getPayerAccountId();
String paymentMethodId = this.getPaymentMethodId();

final int TenUsDollars = 1000;

ProcessPaymentMethodTransaction processPaymentMethodTransaction = new ProcessPaymentMethodTransaction();
processPaymentMethodTransaction.PayerAccountId = payerAccountId;
processPaymentMethodTransaction.PaymentMethodId = paymentMethodId;
processPaymentMethodTransaction.Amount = TenUsDollars;
processPaymentMethodTransaction.CurrencyCode = "USD";
processPaymentMethodTransaction.IsRecurringPayment = false;

return processPaymentMethodTransaction;
 }

 /**
* Gets the proper token URL for the given request.
*
* @returns The URL to be added to the base URL.
*/
 private String getUrl(ProcessPaymentMethodTransaction paymentMethodTransaction) {
String payerId = paymentMethodTransaction.PayerAccountId;

return "/Payers/" + payerId + "/PaymentMethods/ProcessedTransactions/";
 }

 /**
* 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

// ProcessPaymentMethodTransaction.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.
*/

/**
 * Data for processing a tokenized payment method.
 *
 * This example only shows required fields. See the ProtectPay API Manual under
 * "Process a PaymentMethodId" for additional optional fields.
 */
public class ProcessPaymentMethodTransaction {
 /**
* A flag indicating whether this payment is recurring, i.e. repeats on a
* scheduled basis.
*/
 public boolean IsRecurringPayment;

 /**
* The id of the tokenized payment method to process.
*/
 public String PaymentMethodId;

 /**
* The amount to charge in pennies (USD) or smallest unit of currency
* (non-USD) without decimals.
*
* e.g. $1.00 USD is 100 ¥10 JPY is 10 since Japanese Yen does not use a
* decimal place.
*/
 public int Amount;

 /**
* The 3 character currency code (see
* https://en.wikipedia.org/wiki/ISO_4217)
*/
 public String CurrencyCode;

 /**
* The id of the merchant processing profile to use.
*
* Important if the account has multiple processing gateways, e.g. for
* different countries.
*
*/
 public int MerchantProfileId;

 /**
* The account id of the payer that has the payment method.
*/
 public String PayerAccountId;
}

// -------------------------------------------------------------------------------------------- //
// 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;
}

// -------------------------------------------------------------------------------------------- //
// Transaction.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.
*/

import java.math.BigDecimal;

import com.fasterxml.jackson.annotation.JsonProperty;

/**
 * Transaction details.
 *
 */
public class Transaction {
 /**
* The transaction history id in the ProPay system.
*/
 public String TransactionHistoryId;

 /**
* The transaction authorization code from the issuing bank.
*/
 public String AuthorizationCode;

 /**
* The address verification system (AVS) code.
*
* Only present if billing information is present on payment method, or in
* the request.
*/
 @JsonProperty("AVSCode")
 public String AvsCode;

 /**
* The card verification value (CVV) response code.
*/
 @JsonProperty("CVVResponseCode")
 public String CvvResponseCode;

 /**
* The amount in the settled currency.
*/
 public int CurrencyConvertedAmount;

 /**
* The settled currency code.
*/
 public String CurrencyConvertedCurrencyCode;

 /**
* The conversion rate from the requested currency to the settled currency.
* e.g. USD to USD = 1, JPY to USD = 0.0090 (as of 5/17/2017)
*/
 public BigDecimal CurrencyConversionRate;

 /**
* The gross amount in the settled currency.
*/
 @JsonProperty("GrossAmt")
 public Integer GrossAmount;

 /**
* The gross amount less net amount in the settled currency.
*/
 @JsonProperty("GrossAmtLessNetAmt")
 public Integer GrossAmountLessNetAmount;

 /**
* The net amount in the settled currency.
*/
 @JsonProperty("NetAmt")
 public Integer NetAmount;

 /**
* The per transaction fee in the settled currency.
*/
 @JsonProperty("PerTransFee")
 public Integer PerTransactionFee;

 /**
* The percentage fee, if any.
*/
 public BigDecimal Rate;

 /**
* Result information from the transaction.
*/
 public Result ResultCode;

 /**
* The transaction number assigned by the processor.
*/
 public String TransactionId;

 /**
* The transaction result as reported by the processor.
*/
 public String TransactionResult;
}

// -------------------------------------------------------------------------------------------- //
// ProcessPaymentMethodTransactionResponse.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 value returned from call to process a payment method.
 *
 */
public class ProcessPaymentMethodTransactionResponse {
 /**
* The transaction details
*/
 public Transaction Transaction;

 /**
* The result of the request.
*/
 public Result RequestResult;
}

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.

IsRecurringPayment

Boolean

5

Required*

REST ONLY

Valid values are:
true
false

If set to false this transaction will not be marked recurring at the issuer

AchOverrides

Object

-

ACH Only

Used to override the information stored with the ACH PaymentMethodId type

AchOverrides.BankAccountType

String

1

Optional

Valid values are:
Checking
Savings
LoanCredit
GeneralLedger
SEPA (only for use when connecting to specific gateways.)

 

AchOverrides.MandateDate

DateTime

yyyy-MM-dd

Optional*

*If SEPA then value is required.

AchOverrides.MandateDateSigned

DateTime

yyyy-MM-dd

Optional*

*If SEPA then value is required.

AchOverrides.MandateId

String

3

Optional*

*If SEPA then value is required.

AchOverrides.SecCode

String

3

Required*

Standard Entry Class Code.  Valid values are:
PPD
CCD
WEB
TEL
CCD

 

*If the PaymentMethodId type is an ACH type this value is required

CreditCardOverrides

Object

-

Optional

Used to override the information stored with the credit card PaymentMethodId type

CreditCardOverrides.Billing

Object

-

Optional

Used to override the Billing information stored with the credit card PaymentMethodId type

CreditCardOverrides.Billing.Address1

String

50

Optional

Used to override the Address1 stored with the PaymentMethodId.

*Max length is 40 for multi-currency transactions.

CreditCardOverrides.Billing.Address2

String

50

Optional

Used to override the Address2 stored with the PaymentMethodId.

*Max length is 40 for multi-currency transactions.

CreditCardOverrides.Billing.Address3

String

50

Optional

Used to override the Address3 stored with the PaymentMethodId.

*Max length is 40 for multi-currency transactions.

CreditCardOverrides.Billing.City

String

25

Optional

Used to override the City stored with the PaymentMethodId

CreditCardOverrides.Billing.Country

String

3

Optional

Used to override the Country stored with the PaymentMethodId

*Must be ISO 3166 standard 3 character country code.

CreditCardOverrides.Billing.Email

String

100

Optional

Used to override the Email address stored with the PaymentMethodId

CreditCardOverrides.Billing.State

String

3

Optional

Used to override the State stored with the PaymentMethodId

CreditCardOverrides.Billing.TelephoneNumber

Integer

20*

Optional

Used to override the Telephone Number stored with the PaymentMethodId

*10 digits for US numbers.

CreditCardOverrides.Billing.ZipCode

String

10

Optional

Used to override the ZipCode stored with the PaymentMethodId

CreditCardOverrides.CVV

String

4

Optional

CVV code.

If submitting the CVV code with this transaction request it must be passed in the CreditCardOverrides Object

*ProtectPay will not store this value.

CreditCardOverrides.ExpirationDate

String

4

Optional

Used to override the Expiration Date stored with the PaymentMethodId

For a credit card these are submitted as 4 digit numeric values MMYY.

*Required if the Processor Gateway Requires an Expiration Date

CreditCardOverrides.FullName

String

50

Optional

Used to override the Account Name stored with the PaymentMethodId

PayerOverrides

Object

-

Optional

 

PayerOverrides.IpAddress

String

15

Optional

IP address as read from cardholder browser session.

paymentMethodID

GUID

36

Required

This is the ProtectPay ID for the Payment Method, also called a Token

The Payment Method Created Belongs to the PayerId it was Created For

Transaction

Object

-

Required

Contains Transaction Information

*REST passes the transaction values directly and not nested.

Transaction .Amount

Integer

 

Required

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

Transaction.Comment1

String

128

Optional

Transaction descriptor. Only passed if supported by the gateway.

Transaction.Comment2

String

128

Optional

Transaction descriptor. Only passed if supported by the gateway.

Transaction.CurrencyCode

String

3

Required

ISO 4217 standard 3 character currency code.

Transaction.Invoice

String

50

Optional

Recommended. Transaction descriptor-only passed if supported by the gateway.

*ProPay gateway rejects duplicates for same invoice #, card # and amount in 1 minute.

Transaction.IsDebtRepayment

Boolean

5

Optional

Valid Values are:
True
False

 

Only applicable for LegacyProPay and LegacyProPayCan gateways

Defaults to False if not submitted

Transaction.MerchantProfileId

Int(64)

Signed Int(64)

Required

The MerchantProfileId that was created using the supplied credentials for the supplied Gateway that is used to process against this particular gateway

Transaction.PayerAccountId

String

16

Required

This is the ProtectPay ID for the Payer Created and belongs to the BillerID that created it

Transaction.Frauddetectors

Object

-

Optional

Please See ProtectPay Appendix for details concerning the FraudDetectosrObject

Frauddetectorss.FrauddetectorProviderName

String

 

Required*

If using Frauddetectors Object this Element is required.

Response Values

Response Element

Type

Notes

RequestResult.ResultValue

String

The 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 Method Response Code. See Appendix for possible returned values

RequestResult.ResultMessage

String

The Method Response Message. See Appendix for possible returned Messages

Transaction.AuthorizationCode

String

The auth code supplied by the issuing bank. *Only returned on a successful transaction

Transaction.AVSCode

String

AVS response produced by gateway. *Only returned if AVS information is supplied and AVS is supported by the gateway.

Transaction.CurrencyConversionRate

Decimal

The rate for currency conversion used for multi-currency transactions

Transaction.CurrencyConvertedAmount

Integer

Gross converted amount of transaction in the number of [currency] without decimals for multi-currency transactions

Transaction.CurrencyConvertedCurrencyCode

String

The currency the transaction was converted to for multi-currency transactions

Transaction.CVVResponseCode

String

 

Transaction.GrossAmt

Integer

Gross amount of transaction of pennies in USD, or the number of [currency] without decimals.

Not returned for ACH payment transactions.

Transaction.GrossAmtLessNetAmt

Integer

Total amount of fees charged; *ProPay Gateway Only. Not returned for ACH payment transactions.

Transaction.NetAmt

Integer

Net amount of transaction after fees charged; *ProPay Gateway Only. Not returned for ACH payment transactions.

Transaction.PerTransFee

Integer

Per transaction fee; *ProPay Gateway Only. Not returned for ACH payment transactions.

Transaction.Rate

Decimal

Percentage fee; *ProPay Gateway Only. Not returned for ACH payment transactions.

Transaction.ResultCode.ResultCode

String

The result code of the transaction request as reported by ProtectPay. See Appendix for possible returned values.

Transaction.ResultCode.ResultMessage

String

The result message of the transaction request as reported by ProtectPay. See Appendix for possible returned values

Transaction.ResultCode.ResultValue

String

The result value of the transaction request as reported by the ProtectPay. SUCCESS or FAILURE

Transaction.TransactionHistoryId

String

Unique transaction number assigned by ProtectPay.

Transaction.TransactionId

String

Transaction number assigned by processor (Gateway)

Transaction.TransactionResult

String

Transaction result as reported by processor (Gateway)