Hosted Payment Method


Overview

This document provides technical specifications for processing financial transactions through the Tranzpay gateway by interfacing with the Gateway API and a Hosted Payment Page. We have written this specifically for web designers and professionals who design, implement and support the intended systems. We use HTTPS POST to transmit and receive data.

Description:
To reduce your PCI DCSS requirements and liability, and eliminate sensitive card data footprints in your environment, Tranzpay provides a Hosted Payment Page Solution that provides the ability to authorize and capture transactions while adhering to all PCI requirements.

Summary of Steps Required

  1. Send non-secure customer data in initial request to prefill Customer Name, Address, Phone, Email, Policy Number, along with your PostBack and RedirectUrl to capture and store payment results.
  2. Receive encrypted payment link via API Response to prefilled payment form.
  3. Using tokenized payment link, customer will enter payment information and has the option to save information for future use (rebill).
  4. Payment is processed and customer is sent to provided RedirectUrl to view transaction results.
  5. Provided PostBackUrl receives POST response and stores response in database.


Initial Request

  • Request

  • Response

Fieldname

Required

Type

Description

Validate

Xpath

Note

Transaction Type

String

Transaction type to process. (“ThirdParty”))

TransactionType

TranzPayRequest.TransactionType

HTML Encode special characters such as apostrophe for all fields

ProducerID

Integer

TranzPay producerID assigned to your merchant account.

Integer supplied by TranzPay

TranzPayRequest.ProducerID

Cell

UserName

String

TranzPay Username

Username supplied by TranzPay

TranzPayRequest.UserName

Max Len. (60)

Password

String

TranzPay API Key.

API Key supplied by TranzPay

TranzPayRequest.Password

Use API Key from Account Settings

TransactionAmount

Float/Decimal/Integer

Transaction amount in decimal format (ie. 99.99)

Decimal number greater than zero

TranzPayRequest.TransactionAmount

Cell

BillingNameFirst

String

First name

Alpha character name

TranzPayRequest.BillingNameFirst

Max Len. (30)

BillingNameLast

String

Last name

Alpha character name

TranzPayRequest.BillingNameLast

Max Len. (30)

BillingFullName

String

Full Name and/or Business Name

Alpha character name

TranzPayRequest.BillingFullName

Max Len. (80)

BillingAddress

String

Billing street address

Any alphanumeric

TranzPayRequest.BillingAddress

Max Len. (30)

BillingCity

String

Billing city

Any alphanumeric

TranzPayRequest.BillingCity

Max Len. (25)

BillingState

String

Billing state

Any alphanumeric

TranzPayRequest.BillingState

Max Len. (2) Letter Abrev. ex: CA

BillingZipCode

String

Billing zip code

5 digit zip code

TranzPayRequest.BillingZipCode

Cell

PhoneNumber

String

Phone number of account.

10 digit phone number

TranzPayRequest.PhoneNumber

Cell

Email

String

Account holder email

Any alphanumeric

TranzPayRequest.Email

Max Len. (70)

PolicyNum

String

Custom Policy Number Identifier.

Any alphanumeric

TranzPayRequest.PolicyNumber

Cell

RedirectUrl

String

URL the payor will be directed to after payment.

Any alphanumeric

TranzPayRequest.RedirectUrl

Max Len. (165)

PostbackUrl

String

URL to accept Postback API Response.

Any alphanumeric

TranzPayRequest.PostBackUrl

Max Len. (165)

CancelUrl

String

Redirect URL for Cancelled Transactions.

Any alphanumeric

TranzPayRequest.PostBackUrl

Max Len. (165)

ThirdPartyCallID

AlphaNumeric

Merchant supplied unique transaction identifier

Any alphanumeric

TranzPayRequest.ThirdPartyCallID

Max Len. (45)

AddVault

Y or N

Enables option to save payment data in Vault.

Y or N

TranzPayRequest.AddVault

If “No” option to save payment data is not shown

CustomerID

String

Unique Token for Vault entry, min. of 6 characters.

Any alphanumeric

TranzPayRequest.CustomerID

Min. Len (6) Max Len. (45)

Language

es for Spanish or en for English

language to display payment page in

es or en

TranzPayRequest.Language

Max Len. (2)

Format

JSON

If sending Request in JSON format this field is required.

JSON

TranzPayRequest.Format

Max Len. (4)

PostBackFormat

JSON

If Postback Endpoint requires JSON format

JSON

TranzPayRequest.PostBackFormat

Max Len. (4)

UnlockAmount

Y

Pass to make Amount field Editable on Payment Page

Y

TranzPayRequest.UnlockAmount


PaymentType

CC for Credit Card ACH for ACH

Specify payment type presented to customer

CC or ACH

TranzPayRequest.PaymentType

Max Len. (3)


Sample Request

  • Samples

  • xML

  • JSON

<TranzPayRequest>
	<TransactionType> ThirdPartyAddCustomer </TransactionType>
	<UserName> UserName </UserName>
	<Password> APIKEY </Password>
	<ProducerID>ID</ProducerID>
	<BillingNameFirst> John </BillingNameFirst>
	<BillingNameLast> Snow </BillingNameLast>
	<BillingAddress> 100 Sun lane</BillingAddress>		
	<BillingCity> Orlando </BillingCity>
	<BillingState> FL </BillingState>
	<BillingZipCode> 32119 </BillingZipCode>
	<PhoneNumber> 5555555555 </PhoneNumber>
	<Email> [email protected] </Email>
	<RedirectUrl> https://yoururl.org </RedirectUrl>
	<PostBackUrl> https://yourpostbackurl.org </PostBackUrl>
	<CancelUrl> https://yourcancelurl.org </CancelUrl>
	<ThirdPartyCallID> 89170384 </ThirdPartyCallID>
	<AddVault> Y </AddVault>
	<CustomerID> Test123145 </CustomerID>
	<PolicyNumber> 4151231 </PolicyNumber>
</TranzPayRequest>

Notes

ThirdPartyCallID must be unique to every transaction.
PostBackUrl is your API page set up to process a POST request containing results of the transaction.
RedirectUrl is the page the customer will be directed to to view the results of the transaction from the Postback results provided to the PostBackUrl.
CancelUrl is the page the customer will be directed to if the transaction is cancelled before completion, or the session times-out.
AddVault should be “Y” to give customer the option to save payment information for future use in the Customer Vault. If “N” the option will not be displayed to customer.
CustomerID should be a minimum of 6 characters, maximum of 45 characters with no spaces.

To test and view the postback response within the page, it is recommended to use
tranzpaydev.com/testThirdPartyCheck.php in the RedirectUrl field and tranzpaydev.com/testSilentPostBack.php in the PostBackUrl field. These pages are for demonstration purposes only.


Sample Initial Response

  • Samples

  • xML

  • JSON

<TranzPayResponse>
	<link>https://tranzpay.com/?p=35&amp;location=thirdparty&amp;tpID=CzYGZg</link>
</TranzPayResponse>


Postback Response

Fieldname

Required

Type

Description

Validate

Post

Status

String

Transaction Status

SUCCESS or FAILED

Status

TransactionType

String

Transaction type to process. (“ThirdParty”)

ThirdParty

TransactionType

ResponseMessage

String

Transaction Response Message

APPROVED or DECLINED

ResponseMessage

ResponseCode

String

Transaction Response Code

00=Approved

ResponseMessage

CardType

String

Payment method card type

Visa, Mastercard, Discover, American Express

CardType

AccountNumber

Integer

Last four digits of account number

Numeric only

AccountNumber

ExpirationDateMMYY

Integer

2 digit month and 2 digit year

06/24

ExpirationDateMMYY

PaymentMethod

String

Transaction Payment Type (CC or ACH)

Cell

PaymentMethod

TransactionDate

DateTime

TransactionDate

Cell

02/04/2020 1:21:30 pm

TransactionAmount

String

Transaction Amount

Float

TransactionAmount

AuthCode

Integer

Authorization Code

Any alphanumeric

AuthCode

AvsRsltCode

String

AVS Result Code

‘Y’or ‘N’

AvsRsltCode

TransactionID

Integer

Id unique to transaction on the payment gateway

Cell

TransactionID

CVV2ResponseMessage

String

CVV2 Response Message

Cell

CVV2ResponseMessage

CVV2ResponseCode

String

CVV2 Response Code

Cell

CVV2ResponseCode

ThirdPartyCallID

String

Unique ID assigned by merchant for transaction.

Any alphanumeric, Max Len (45)

ThirdPartyCallID

AddVault

String

‘Y’ if the payment data was saved to Vault. ‘N’ for No.

‘Y’or ‘N’

AddVault

CustomerID

String

Token ID for Vault Entry (Saved Payment Information)

Any alphanumeric

Min. Len (6) Max Len. (45)

PolicyNum

String

Customer policy number or equivalent.

Any alphanumeric

PolicyNum

Error

String

Returned error Message.

Any alphanumeric

Error

StatusMessage

String

Status Message

Any alphanumeric

Status Message


Sample Postback Success Return

  • Samples

  • xML

  • JSON

'Status' => string 'SUCCESS' 
'TransactionType' => string 'ThirdParty' 
'ResponseMessage' => string 'APPROVED'
'ResponseCode' => string '00'
'CardType' => string 'Visa'
'AccountNumber' => string '4747' 
'ExpirationDateMMYY' => string '06/24' 
'PaymentMethod' =>string 'cc' 
'TransactionDate' => string '2019-10-30 15:01:04' 
'TransactionAmount' => string '14.9900' 
'AuthCode' => string '546621' 
'AvsRsltCode' =>string 'Y' 
'TransactionID' => string '133293018' 
'CVV2ResponseMessage' => string 'CVV MATCH' 
'CVV2ResponseCode' => string 'M' 
'ThirdPartyCallID'=> string '12351256' 
'AddVault'=> string 'Y' (will return 'N' if unsuccessful)
'CustomerID'=> string '124367' (will return 'NULL' if not added)
'PolicyNum'=> string '13513123'
'Error'=> string 'NONE' (error note can change)
'StatusMessage' =>string 'NONE' (status message can change)


Sample Postback Failed Return

  • Samples

  • xML

  • JSON

'Status' => string 'FAILED' 
'TransactionType' => string ' ThirdParty' 
'ResponseMessage' => string 'DECLINED'
'ResponseCode' => string '605'
'CardType' => string 'Visa'
'AccountNumber' => string '4747' 
'ExpirationDateMMYY' => string '06/24' 
'PaymentMethod' => string ' CC' 
'TransactionDate' => string '2019-10-30 15:01:04' 
'TransactionAmount' => string '14.9900' 
'AuthCode' => string '546621' 
'AvsRsltCode' => string 'Y' 
'TransactionID' => string '133293018' 
'CVV2ResponseMessage' => string 'CVV MATCH' 
'CVV2ResponseCode' => string 'M' 
'ThirdPartyCallID'=> string '12351256' 
'AddVault'=> string 'N' 
'CustomerID'=> string '124367' 
'PolicyNum'=> string '13513123'
'Error'=> string 'Customer ID already exists' (note error can change)
'StatusMessage' => string 'DUPLICATE TRANSACTION'

Notes:
Values above can be fetched in PHP via $_POST variables. Example: on the Post Back url page just use $_POST[‘Status’] to fetch “SUCCESS” or “FAILED”.

Even if Initial Request passes AddVault=Y, if the customer does not opt to save payment information for future use (via the checkbox to save payment information), the Postback will exclude a CustomerID and return AddVault=N. This is the same for both SUCCESS and FAILED transaction responses.


Methodology

Postback response contains ‘TransactionID’ and ‘CustomerID’ if the customer’s information was successfully added the vault. Using the ‘TransactionID’ or ‘CustomerID’ the following functions are available:

Voiding a transaction:

Supply the TransactionID from the original transaction, and utilize the CreditCardVoid or the ACHVoid request. Transactions may only be voided before they settle. For settled transactions, please see Refunding a Transaction below.

Refunding a transaction:

After a transaction has settled, you will need to issue a refund, rather than void. Provide a TransactionID and TransactionAmount to utilize the CreditCardCredit or the ACHRefund request.

Check Status:

To check the status of a transaction, use the TransactionID and utilize the GetTransaction request.

Rebilling a Customer:

To rebill a customer that was previously added to the Customer Vault, provide the CustomerID and then utilize one the following API requests:

Credit Card: AddCustomerCCCharge
ACH: AddCustomerACHDebit

Updating a Vault Record:

To update a customer record in the vault, provide the CustomerID and utilize the UpdateCustomer request.

View Vault Record:

To view details of a previously stored Vault record, provide the CustomerID and utilize the GetCustomer API Request.