Hosted Vault Method


Overview

This document provides technical specifications for adding customer information and financial data for future rebills through the Tranzpay gateway by interfacing with the Gateway API and a Hosted Vault Entry Page. We have written this specifically for web designers and professionals who 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 Vault Solution that provides the ability for customers to add their payment information for future rebills 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 link via API Response to prefilled vault entry form.
  3. Using tokenized link, customer will enter payment information to store in PCI secure vault for future use (rebill).
  4. Data is saved and customer is sent to provided RedirectUrl.
  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. (“ThirdPartyAddCustomer”)

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

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)

PolicyNumber

String

Custom Policy Number

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

Max Len. (100)


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 saved entry.
RedirectUrl is the page the customer will be directed to to view the results of the saved entry from the Postback results provided to the PostBackUrl.
CancelUrl is the page the customer will be directed to if the vault entry is cancelled before completion, or the session times-out.
AddVault should be “Y” to save payment information for future use in the Customer Vault.
CustomerID should be a minimum of 6 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=thirdpartyAddCustomer&amp;tpID=CzYGZg</link>
</TranzPayResponse>


Postback Response

Fieldname

Required

Type

Description

Validate

Post

Status

String

Transaction Status

SUCCESS or FAILED

Status

CustomerID

String

Token ID for Vault Entry (Saved Payment Information)

Any alphanumeric

CustomerID

TransactionType

String

Transaction type. (“ThirdPartyAddCustomer”)

ThirdPartyAddCustomer

TransactionType

BankRoutingNumber

String

Bank Routing Number.

9 Digit Routing Number

BankRoutingNumber

AccountNumber

String

Bank Account Number.

Last 4 Digits of Account Number

AccountNumber

BankAccountType

String

Bank Account Type.

CH = Checking SV = SAVINGS

BankAccountType

CardType

String

Payment method card type.

Visa, Mastercard, Discover, Amex

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

AddDate

DateTime

AddDate

Cell

02/04/2020 1:21:30 pm

ThirdPartyCallID

String

Unique ID assigned by merchant for transaction.

Any alphanumeric

ThirdPartyCallID

PolicyNumber

String

Customer policy number or equivalent.

Any alphanumeric

PolicyNumber

Error

String

Returned error Message.

Any alphanumeric

Error


Sample Postback Success Return

  • Samples

  • xML

  • JSON

'Status' => string 'SUCCESS' 
'TransactionType' => string 'ThirdPartyAddCustomer' 
'CustomerID'=> string '124367' (will return 'NULL' if not added)
'BankRoutingNumber'=> string ''
'AccountNumber' => string '4747'
'BankAccountType'=> string '' 
'BillingNameFirst'=> string 'John'
'BillingNameLast'=>string 'Snow'
'BillingFullName'=> string 'John Snow'
'Billing Address'=> string '100 Sun lane'
'BillingCity'=> string 'Orlando'
'BillingState'=> string 'FL'
'BillingZipCode'=> string '32119'
'Email'=> string '[email protected]'
'PhoneNumber'=> string '5555555555'
'CardType' => string 'Visa'
'ExpirationDateMMYY' => string '06/24' 
'PaymentMethod' => string ' CC' 
'AddDate' => string '2019-10-30 15:01:04' 
'PolicyNumber'=> string '13513123'
'Error'=> string 'NONE' (error note can change)


Sample Postback Failed Return

  • Samples

  • xML

  • JSON

'Status' =>string 'FAILED' 
'TransactionType' => string ' ThirdPartyAddCustomer' 
'CustomerID'=> string 'NULL' (will return 'NULL' if not added)
'BankRoutingNumber'=> string ''
'AccountNumber' => string '4747'
'BankAccountType'=> string '' 
'BillingNameFirst'=> string 'John'
'BillingNameLast'=> string 'Snow'
'BillingFullName'=> string 'John Snow'
'Billing Address'=> string '100 Sun lane'
'BillingCity'=> string 'Orlando'
'BillingState'=> string 'FL'
'BillingZipCode'=> string '32119'
'Email'=> string '[email protected]'
'PhoneNumber'=> string '5555555555'
'CardType' => string 'Visa'
'ExpirationDateMMYY' => string '06/24' 
'PaymentMethod' => string ' CC' 
'AddDate' => string '2019-10-30 15:01:04' 
'PolicyNumber'=> string '13513123'
'Error'=> string 'Customer ID already exists' (note error can change)

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”.


Methodology

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

Billing a Customer:

To bill a vaulted 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.

Demo Account Credentials

Log on to Tranzpay’s Demo Account to explore the payment gateway at https://demo.tranzpay.com. You many verify your transactions processed successfully by using listed credentials or by using any credit card. Data created with test credentials will never hit the credit card networks and are void of costs.

Demo Account


User Name

demo

Password

[email protected]

Producer ID

13

API Password

$2y$10$IjbpcESE0QPw4OHmjlR3Oeu5M1i6a7xqMuP/gWr6Ly4sPY3GeYD8q

Test Server

https://demo.tranzpay.com/api/transaction.php

Production Server

https://www.tranzpay.com/api/transaction.php

Test transactions can be submitted with the following information:

Card Type

Card Number

Visa

4747474747474747

MasterCard

5431111111111111

Discover

6011601160116611

American Express

341111111111111

Test Server

https://demo.tranzpay.com/api/transaction.php

Production Server

https://www.tranzpay.com/api/transaction.php