First Data Payeezy Gateway Web Service API Reference Guide

1 Intended Audience

This document is intended for

  • Developers who want to understand and implement the First Data Payeezy Gateway Web Service API

2 Introduction

The First Data Payeezy Gateway Web Service API is a web service that allows third-party applications to process transactions through the Payeezy Gateway system. The range of processing scenarios (Purchase, Refund, Pre-Authorization, etc.) enable flexible and powerful ways to implement custom business logic. First Data also provides free client libraries that ease integration with the Payeezy Gateway Web Service API.

The Payeezy Gateway Web Service API is available in both SOAP and REST, where the latter supports XML and JSON message formats. The same range of transaction processing scenarios is supported regardless of which style Payeezy Gateway Web Service API you choose.

 

IMPORTANT NOTE: ALL TAGS MUST BE SUBMITTED THROUGH THE API IN THE SAME CASE AS SHOWN BELOW.

2.1 Basic Information

IMPORTANT: Please check release notes for important information regarding changes and bug fixes. You can find this in Appendix 1. More About Service URLs.

The service URLs are:

Important Note about v12 or higher of the Web Service API: Merchants wishing to use V12 or higher of the API must implement the API HMAC hash security calculation. Further information on this subject can be found here.

To submit API transactions to the demo environment, please use the hostname api.demo.globalgatewaye4.firstdata.com instead of the above.

Two pieces of information must be provided when you submit a transaction via the Payeezy Gateway Web Service API, they are:

  • Exact ID - also known as the Gateway ID, this value identifies the Merchant and Terminal under which the transaction is to be processed
  • Password - authenticates the Payeezy Gateway Web Service API request, this value should not be exposed to the public

These credentials can be submitted in two ways:

  • as HTTP Basic Authentication user name and password values
  • as part of the Payeezy Gateway Web Service API message via the ExactID and Password properties

The Gateway ID can be found on the Administration tab under Terminals and then Details. Also from that screen you can set up your password by clicking on "Generate" or change the existing password. Password must be a minimum of 8 characters with at least one letter and number and should contain only letters, numbers, dashes (-), and underscores (_). You must then click on "Update" at the bottom of that screen.

When using the automatic generator to create a password it should be noted that the generator creates a 32 character password.

The Password Generator for the API Interface (located on the Terminal Screen in the RPM) has been updated, it will now generate a 32 character password.

If a shopping cart is integrated to a merchant (now) they won't be affected. BUT, if that same cart does an integration with a new merchant, the cart will need to increase their character capacity to support the new 32 character length.

Password Generation/Use:

  • Log into Payeezy Gateway
  • Access Terminal details screen
  • Copy your GatewayID and paste it into your cart
  • Select the Generate Password, this option will create a new 32 character password
  • Copy the Password and paste it into your cart

For carts that do not accept 32 characters

  • You can do one of the following steps:
  • An error will be generated when you attempt to paste / input or save the 32 character password
  1. Create your own password (manually enter) in the Payeezy Gateway Terminal Screen and update both the Gateway and the Cart with this new value or
  2. Delete the extra characters in the Gateway generated Password and then update both the Gateway and the care with this new value
  3. Update the Terminal after either generating or creating the password.

3 Special Transactions

The following tables show which fields are required to be submitted when using v9 or higher of the API. The first chart applies to regular transactions only; required properties for TransArmor and ValueLink transactions are handled in their own tables below.

 

Transaction Name Transaction Type Required Properties
Purchase 00

CardholdersName

Card_Number

DollarAmount

Expiry_Date

Pre-Authorization 01

CardholdersName

Card_Number

DollarAmount

Expiry_Date

Pre-Authorization Completion

02* (Recommended

use code 32 instead)

CardholdersName

Card_Number

DollarAmount

Expiry_Date

Authorization_Num

Refund 04

CardholdersName

Card_Number

DollarAmount

Expiry_Date

Void 13

CardholdersName

Card_Number

DollarAmount

Expiry_Date

Authorization_Num

Tagged Pre-Authorization Completion 32*

Transaction_Tag

DollarAmount

Authorization_Num

Tagged Void 33

Transaction_Tag

DollarAmount

Authorization_Num

Tagged Refund 34

Transaction_Tag

DollarAmount

Authorization_Num

 

 

3.1 PayPal Transactions

PayPal transactions can be voided or refunded. Note that voids can only be run against pre-authorizations to clear them; to return funds to a customer that have already been captured the refund transaction type must be used. PayPal pre-authorizations will expire in 29 days if they are not completed.

Transaction Name Transaction Type Required Properties
Order 07

CardHoldersName

DollarAmount

Authorization

PayerID

Success

CorrelationID

Message

CardType (set to "PayPal")

Pre-Authorization 01

CardHoldersName

DollarAmount

Authorization

PayerID

Success

CorrelationID

Message

CardType (set to "PayPal")

Purchase 00

CardHoldersName

DollarAmount

Authorization

PayerID

Success

CorrelationID

Message

CardType (set to "PayPal")

Tagged Completion 32

Transaction_Tag

DollarAmount

Tagged Void 33

Transaction_Tag

DollarAmount

Tagged Refund 34

Transaction_Tag

DollarAmount

 

3.2 Zero Dollar Pre-Authorizations

Zero dollar Authorizations can be performed within the Payeezy Gateway Web Service API. Typically this is done in scenarios where the card details need to be verified and tokenized, but not charged immediately. Performing this type of transaction can be done by submitting "0" as the dollar amount and submitting "Transaction_type" as "Pre-Authorization Only". In addition, if TransArmor Multi-Pay token processing is enabled for the merchant account, TransArmor Multi-Pay tokens will be returned for each submitted transaction. The returned Multi-Pay tokens, from the Payeezy Gateway Web Service API or Hosted Payment Pages, can be utilized within the Payeezy Gateway Web Service interface to initiate subsequent transactions or as a mechanism to issue voids or credits to the underlying credit card number referenced by the Multi-Pay token.

3.3 ValueLink Transactions

ValueLink gift cards are supported by the Payeezy Gateway Web Services API. ValueLink cards are treated as a method of payment such as MasterCard. Note that partial authorizations are enabled for ValueLink transactions by default. This means that a transaction will be considered as approved if only a partial amount of the funds requested is available on the card. This transaction performs redemption/purchase on an active account. If the requested amount is greater than the account balance, the account will be reduced to zero, and collect the difference from consumer with other form of payment. Partial authorization is the difference of the requested amount and the account balance. The merchant’s application is responsible for determining how much was actually taken from the account by looking at the Previous Balance, and Current Balance, then that difference is applied to the redemption in order to determine if the entire transaction was satisfied. Should the consumer decline to pay by other means, the transaction would be voided. Each type of ValueLink transaction has its own optional and required properties, which are listed in the chart below. NOTE:

  • When processing ValueLink transactions, version 9 or higher of the API endpoint must be used.
  • NOTE: ValueLink is primarily supported through the Payeezy Gateway Web API interface (integration) and HCO (Hosted Checkout). Only refunds and voids are supported in the RPM Transaction tab.
  • Payeezy Gateway is certified SVdot Internet message format through Compass host.
  • ValueLink has the ability support partial approvals. The Approved Amount will be returned and the Integrator will be responsible for handling the request for additional form(s) of payment in the integrated solution.

     

    Example:

     

    TYPE: Purchase

     

    ACCT: Gift Card $ 50.00 USD

    ($ 62.00 was requested)

     

    CARD NUMBER : ############0137

    DATE/TIME : 03 Mar 13 18:24:38

    REFERENCE # : 001 0159477 M

    AUTHOR. # : 1

    TRANS. REF. :

     

    Approved - Thank You 100

Transaction Name Transaction Type Required Properties
Purchase

00

CardHoldersName

Card_Number

DollarAmount

CardType (set to "Gift")

Refund

04

CardHoldersName

Card_Number

DollarAmount

CardType (set to "Gift")

Authorization_Num

Void

13

CardHoldersName

Card_Number

DollarAmount

CardType (set to "Gift")

Authorization_Num

Tagged Void

33

Transaction_Tag

DollarAmount

Authorization_Num

CardType (set to "Gift")

Tagged Refund

34

Transaction_Tag

DollarAmount

Authorization_Num

CardType (set to "Gift")

CashOut

83

CardHoldersName

Card_Number

CardType (set to "Gift")

ValueLink Activation

85

CardHoldersName

Card_Number

DollarAmount

CardCost

CardType (set to "Gift")

Balance Inquiry

86

CardHoldersName

Card_Number

CardType (set to "Gift")

Reload

88

CardHoldersName

Card_Number

CardType (set to "Gift")

DollarAmount

ValueLink Deactivation

89

CardHoldersName

Card_Number

CardType (set to "Gift")

 

Example ValueLink Activate Virtual Card

 

  • For a Virtual gift card activation
  • The “virtual_card” parameter must be set to True and
  • The appropriate “VL PromoCode” must be passed (this value is as assigned by VL based on the Client’s program), it is passed in the “Customer_ref” field as shown in the request packet below.
  • There are 5 PromoCode values and as stated above, these are assigned by VL based on the Client’s program
    • 29296 & 29297 will cause an 8-digit EAN to be generated and returned in the response
    • 29298 generates a 4-digit EAN to be generated and returned in the response
    • 28407 & 28408 cause no EAN to be generated

 

Activation Request:


curl -u 'GatewayID:Password' \
-H 'Content-Type: application/json; charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"transaction_type":"85",
"credit_card_type":"Gift",
"virtual_card":true,
"customer_ref":"29297",
"amount":"100.00",
"cardholder_name":"Activate Virtual Gift card",
"reference_no":"VL-Activation",
"card_cost":"100.00"
}' \
https://api.demo.globalgatewaye4.firstdata.com/transaction

 

Activation Response:

{"error_number":0,
"transaction_error":0,
"transaction_approved":1,
"exact_resp_code":"00",
"exact_message":"Transaction Normal",
"bank_resp_code":"100",
"bank_message":"Approved",
"sequence_no":"000111",
"retrieval_ref_no":"5807370",
"merchant_name":"Test Account",
"merchant_province":"Alabama",
"merchant_country":"United States",
"current_balance":100.0,
"previous_balance":0.0,
"ctr":"========== TRANSACTION RECORD ==========\nTest Account\n\n, AL\nUnited States\n\n\nTYPE: Activate Card\n\nACCT: Gift Card $ 100.00 USD\n\nCARDHOLDER NAME : Activate Virtual Gift card\nCARD NUMBER : ##########4396\nDATE/TIME : 18 Aug 15 17:31:02\nREFERENCE # : 001 000111 V\nAUTHOR. # : ET125408\nTRANS. REF. : Testing-VL-Activatio\n\n Approved - Thank You 100\n\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================",
"gateway_id":"A99999-99",
"transaction_type":"85",
"amount":100.0,
"cc_number":"7777999999999999",
"transaction_tag":59473592,
"authorization_num":"ET125408",
"cardholder_name":"Activate Virtual Gift card",
"cvd_presence_ind":0,
"reference_no":"Testing-VL-Activatio",
"customer_ref":"29297",
"client_ip":"************",
"currency_code":"USD",
"partial_redemption":0,
"credit_card_type":"Gift Card",
"ean":"82433100",
"virtual_card":true,
"card_cost":"100.00"}%

3.4 TransArmor Transactions

Note that if TransArmor is enabled, versions 9 or higher of the API must be used.

Transaction Name Transaction Type Required Properties
Purchase 00

CardHoldersName

TransarmorToken

DollarAmount

CardType

Expiry_Date

Pre-Authorization 01

CardHoldersName

TransarmorToken

DollarAmount

CardType

Expiry_Date

Pre-Authorization Completion 02

CardHoldersName

TransarmorToken

DollarAmount

CardType

Authorization_Num

Expiry_Date

Forced Post 03

CardHoldersName

TransarmorToken

DollarAmount

CardType

Authorization_Num

Expiry_Date

Refund 04

CardHoldersName

TransarmorToken

DollarAmount

CardType

Expiry_Date

Pre-Authorization Only 05

CardHoldersName

TransarmorToken

DollarAmount

CardType

Expiry_Date

Void 13

CardHoldersName

TransarmorToken

DollarAmount

CardType

Authorization_Num

Expiry_Date

From a web service interface, the following fields are utilized for inbound/outbound TransArmor multi-pay token information (sample simplified and unnecessary fields removed):

<TransactionResult>

<Card_Number></Card_Number> -- Blank on a TransArmor response. Needed to request a TransArmor token.

<Expiry_Date>0412</Expiry_Date>

<EXact_Resp_Code>00</EXact_Resp_Code>

<EXact_Message>Transaction Normal</EXact_Message>

<Bank_Resp_Code>100</Bank_Resp_Code>

<Bank_Message>Approved</Bank_Message>

<Bank_Resp_Code_2></Bank_Resp_Code_2>

<SequenceNo>0000165</SequenceNo>

….

<TransarmorToken>445747AACD2D1111</TransarmorToken> -- Present on TransArmor response, Needed on Token request

<CardType>Visa</CardType> -- Present on TransArmor response, Needed on Token request.

Using TransArmor Tokens with a Test Account

In the test account environment the TransArmor token is returned as random letters and numbers with the last 4 digits the same as the card number. In the production environment the token is returned as only random numbers with the last 4 digits the same as the card number.

 

3.5 Telecheck Transactions

The v13 endpoint of the API adds support for Telecheck transactions. Purchase, void, and tagged refund are the transaction types supported for Telecheck.

NOTE: When processing TeleCheck transactions through the API, your TeleCheck merchant account will need to be set up for ICA (Internet Check Acceptance). You will also need to set the ECI indicator property to match the type of business you are in order for your request to successfully process.

 

Transaction Name Transaction Type Required Properties
Purchase 00

DollarAmount

CheckNumber

CheckType

CustomerName

BankAccountNumber

BankRoutingNumber

CustomerIDType

CustomerID

Client_Email

Address

Void 13

DollarAmount

CheckNumber

CheckType

CustomerName

BankAccountNumber

BankRoutingNumber

CustomerIDType

CustomerID

Client_Email

Address

Authorization_Num

Tagged Void 33

Transaction_Tag

DollarAmount

Authorization_Num

Tagged Refund 34

Transaction_Tag

DollarAmount

Authorization_Num

Updated 02/03/14 MW

 

3.6 Visa Checkout Transactions

The v19 endpoint and newer versions of the API adds support for Visa Checkout transactions.

When using Visa Checkout via the API, the button placement and order entry need to be handled by the merchant.

Important: when using the Payeezy API for Visa Checkout, you are also required to maintain your own Visa Checkout API key. Visa Checkout automatically creates an API key when you enabled your Terminal for Visa Checkout via the Payeezy Gateway. You will use both a live key and a sandbox key from Visa Checkout (these will be different values). Your Visa Checkout API key can be retrieved from the Visa Checkout web-portal. The link to the web-portal was automatically emailed to the email account associated with the Payeezy Gateway Terminal.

 

Branding of the Visa Checkout button

When presenting the Visa Checkout button, the merchant must follow all of the Visa Checkout branding requirements. These requirements describe how to use Visa Checkout visual assets on your site. See the Visa Checkout JavaScript Integration section for integration details.

 

Visa Checkout Asset Inventory

Important: Visa may update or change Visa Checkout assets in order to improve the user experience at any time.

 

Visa Checkout Buttons

Standard button without card art:

Neutral button without card art:

Button with card art:

 

Visa Checkout Acceptance Marks

Note: The non-stacked mark (right-most graphic above) is preferred.

 

General Visa Checkout Asset Placement and Usage Requirements

You are required to implement the Visa Checkout branding requirements on all pages where the consumer is presented a payment method option, such as Visa Checkout or another payment method. Common examples include shopping cart page, login page, product page, and payment page. Your actual implementation depends on your specific flow.

 

You can use Visa Checkout on any page or in any flow on your site or application where a consumer is asked to type in their billing and payment information. Common examples include cart pages (both full and mini pages), payment pages, card-on-file management pages, or immediately before a flow where a consumer is prompted for personal information, which may be available, at least partially, within Visa Checkout.

 

These rules apply to the Visa Checkout button and acceptance mark:

  • Do not change the functionality of these assets.
  • Do not alter the size, shape, orientation or any other aspect of the images. In the event an image is not sized properly, Visa will provide an alternative variation.
  • Ensure buttons are placed on an equal level with other action items on the page, regardless of the orientation of the page. If the buttons are below the fold, it helps to place an additional button at the top of the page:

 

Visa Checkout Button Requirements

The Visa Checkout button enables a consumer to pay for items with Visa Checkout on your site. The following rules are specific to the Visa Checkout button:

  • You can use either a horizontal or stacked implementation with ‘or’ text between payment options to emphasize and distinguish that users are making a selection:
  • If you offer guest checkout, pre-fill any account creation form you provide using the information provided from Visa Checkout after the lightbox closes.
  • You should use the standard button unless the background colors on your site are dark, in which case, you can consider using a neutral button to provide greater contrast. Note: The neutral button is not available in the Visa Checkout SDK for iOS or the Visa Checkout SDK for Android.

As a best practice, if you require the consumer to sign in to your site, link the consumer's Visa Checkout account to the consumer's account on your site to avoid multiple sign in's by the consumer during checkout. By linking accounts, you can recognize the consumer's account on your site based on the consumer's successful sign in to Visa Checkout.

 

Visa Checkout Acceptance Mark Requirements

Use the Visa Checkout acceptance mark to let consumers know you accept Visa Checkout on your pages, such as on your payment pages and other pages that display a payment method. They are available at the following URLs:

 

  • Preferred acceptance mark, 99x34 pixels:

URL: https://assets.secure.checkout.visa.com/VmeCardArts/partner/POS_horizontal_99x34.png

 

  • 40x30 pixels:

URL: https://assets.secure.checkout.visa.com/VmeCardArts/partner/POS_vertical_medium_40x30.png

 

  • 49x31 pixels:

URL: https://assets.secure.checkout.visa.com/VmeCardArts/partner/POS_vertical_large_49x31.png

 

  • 28x21 pixels:

URL: https://assets.secure.checkout.visa.com/VmeCardArts/partner/POS_vertical_small_28x21.png

 

The following rules are specific to the Visa Checkout acceptance mark:

  • Add Visa Checkout as the alternative (alt) text for the image.
  • The Visa Checkout acceptance mark is not a substitute for the Visa brand mark.
  • If the page layout cannot accommodate the acceptance mark, you can use the full Visa Checkout text instead.

 

Use on Payment Pages

Payment pages are those in which you accept a payment with the Visa Checkout button. The following rules apply:

  • Place the Visa Checkout acceptance mark next to a selector, such as a radio button:

 

  • When Visa Checkout has been selected, display the Visa Checkout button and hide the input fields for other payment methods:

 

Identifying Accepted Payment Methods

If you display accepted payment methods, include the Visa Checkout acceptance mark.

 

Visa Checkout Messaging

These examples provide specific content that you can use to describe Visa Checkout to consumers. Use either the short statement or long statement.

 

Short Statement

With Visa Checkout, you now have an easier way to pay with your card online, from the company you know and trust. Create an account once and speed through your purchase without re-entering payment or shipping information wherever you see Visa Checkout.

 

Long Statement

Visa is making it easier to pay with your card online.

  • Create an account once and speed through checkout without having to re-enter payment or shipping information wherever you see Visa Checkout.
  • Checkout with a single username and password across the sites you love to shop.
  • Visa secures access to your account with advanced security tools, so you can shop online with confidence.
  • Consistent, simple experience across desktop, mobile web and apps.
  • Easy to activate with any major credit or debit card.
  • Earn the same great rewards with the card you already use. Seamless web and mobile checkout without ever leaving merchant site.

 

Placement of the Visa Checkout button

 

Visa Checkout JavaScript and Button Reference sdk.js JavaScript Library

Important: the API key mentioned in this section is the Visa Checkout API key. You are required to maintain your own Visa Checkout API key. Visa Checkout automatically created an API key when you enabled your Terminal for Visa Checkout via Payeezy Gateway. You will use both a live key and a sandbox key from Visa Checkout, which are different from each other. Your Visa Checkout API key can be retrieved from the Visa Checkout web-portal. The link to the web-portal was automatically emailed to the email account associated with the Payeezy Gateway Terminal.

 

Use the sdk.js JavaScript library to control the operation of Visa Checkout on your site. There is one version for sandbox testing and one for live:

Example

<body>

...

<script type="text/javascript"

src="https://sandbox-assets.secure.checkout.visa.com/

checkout-widget/resources/js/integration/v1/sdk.js">

</script>

</body>

 

v-button Image Class

Use the v-buttoning class to render a Visa Checkout button that a consumer clicks to initiate a payment. The rendered buttons must follow the Visa Checkout user interface guidelines, which are described in Getting Started With Visa Checkout.

 

Query Parameters

Parameter

Description

size

(Optional) Width of the button, in pixels.

You can either specify the size to display a standard sized button, or you can specify height and width to specify a custom size button. If you do not specify either the size or both height and width, the button size is 213 pixels. If you specify height or width, the value of size is ignored.

 

Format: It is one of the following values:

• 154 - small

• 213 - medium (default)

• 425 - High resolution or large

Any other value defaults to 213 pixels.

 

Example: size=154

Since 2.0

height

Height of the button, in pixels, for custom button sizes.

You must specify the height if you specify a value for width. The value you choose determines the range of allowable values for width.

 

Format: It is one of the following values:

• 34

• 47

• 94

 

Example: height=94

Since 2.4

width

Width of the button, in pixels, for custom button sizes. You must specify the width if you specify a value for height.

 

Format: It is one of the following values:

• less than 477 if height is 34; default value is 154

• greater than 476 and less than 659 if height is 47; default value is 213

• greater than 658 and less than 1317 if height is 94; default value is 425

The default value is used if the value for width is invalid for the specified height.

 

Example: width=200

Since 2.4

locale

(Optional) The locale, which controls how text displays in a Visa Checkout button and the Visa Checkout lightbox. If not specified, the Accepted-Language value in HTTPS header is used, or if not present, en_US is used.

 

Format: It is one of the following values:

• en_US - American English

• en_CA - Canadian English

• fr_CA - Canadian French

• en_AU - Australian English

 

Example: locale=en_US

Since 2.0

color

(Optional) The color of the Visa Checkout button.

 

Format: It is one of the following values:

• standard (default)

• neutral

 

Note: Any other value for color will default to standard.

 

Example: color=neutral

Since 2.5

cardBrands

(Optional) Override value for brands associated with card art to be displayed. If a brand matching the consumer's preferred card is specified, the card art is displayed on the button; otherwise, a generic button is displayed.

 

Format: Comma-separated list of one or more of the following brands:

• VISA

• MASTERCARD

• AMEX

• DISCOVER

 

Example: cardBrands=VISA,AMEX

Since 2.0

acceptCanadianVisaDebit

Whether a Canadian merchant accepts Visa Canada debit cards; required for Canadian merchants, otherwise, ignored.

 

Format: One of the following values:

• true - Visa Canada debit cards accepted

• false - Visa Canada debit cards not accepted

 

Example: acceptCanadianVisaDebit : "true"

Since 2.0

 

 

Examples

<body>

...

<img alt="..." class="v-button" role="button" src=

"https://sandbox.secure.checkout.visa.com/wallet-services-web/xo/button.png?..."

/>

...

</body>

 

Note: You can specify tabbing behavior to the button by including the tabindex attribute:

 

<img alt="..." class="v-button" role="button" tabindex="0" src=

"https://sandbox.secure.checkout.visa.com/wallet-services-web/xo/button.png?..."

/>

 

 

onVisaCheckoutReady Function

You control the Visa Checkout button and lightbox operation by defining an onVisaCheckoutReady function that includes handlers for initialization and purchase events. The function includes 2 kinds of event handlers:

Event Handler

Description

V.init

(Required) Event handler for initialization. Specify values for initialization in this handler.

Since 2.0

V.on

(Required) Event handler for Visa Checkout purchase events. Specify actions to take on the following Visa Checkout events:

• payment.success

• payment.cancel

• payment.error

Since 2.0

 

Example

<head>

...

<script type="text/javascript">

function onVisaCheckoutReady(){

V.init({ apikey: "merchantApikey",... });

V.on("payment.success", function(payment){ ... });

V.on("payment.cancel", function(payment){ ... });

V.on("payment.error", function(payment, error){ ... });

}

</script>

...

</head>

 

 

V.init Event Handler

Use the V.init event handler to specify a JSON object that contains initialization values for the Visa Checkout JavaScript library. You specify values for these properties:

Property

Description

apikey

(Required) The API key that Visa Checkout created when you enabled your Terminal for Visa Checkout via the Gateway.

 

You will use both a live key and a sandbox key from Visa Checkout, which are different from each other. The API key from Visa Checkout can be retrieved from the Visa Checkout web-portal. The link to the web-portal was automatically emailed to the email account associated with the Gateway Terminal.

 

Format: Alphanumeric; maximum 100 characters

Since 2.0

externalProfileId

(Optional) Profile ID (also the profile's name), created externally by a merchant or partner. Visa Checkout uses this to populate settings, such as accepted card brands and shipping regions. The properties set in this profile override properties in the merchant's current profile.

 

Format: Alphanumeric; maximum 50 characters

Since 2.0

externalClientId

(required or optiona) Unique ID associated with the client, such as a merchant, which could be assigned by you or Visa Checkout.

 

Format: Alphanumeric; maximum 100 characters

Since 2.0

sourceId

(Optional) Your merchant reference ID.

 

Format: Alphanumeric; maximum 100 characters

Since 2.0

settings

(Optional) One or more name-value pairs, each of which specifies a configuration attribute.

 

Format: settings=xxxxx?

Since 2.0

paymentRequest

(Optional) One or more name-value pairs, each of which specifies a payment request attribute.

 

Format: paymentRequest=xxxx?

Since 2.0

 

 

Settings Properties

Property

Description

locale

(Optional) Override value for the locale, which controls how text displays in the Visa Checkout button and lightbox. By default, Visa Checkout determines the locale from the consumer's browser settings. Do not use the locale attribute unless explicit control over the button or lightbox locale is required.

 

Format: It is one of the following values:

• en_US - American English

• en_CA - Canadian English

• fr_CA - Canadian French

• en_AU - Australian English

 

The value of the locale attribute must be compatible with the value of the country attribute.

Since 2.0

countryCode

(Optional) Override value for the country code, which controls how text displays in the Visa Checkout button and lightbox. By default, Visa Checkout determines the country from the consumer's IP address. Do not use the countryCode attribute unless explicit control over the display is required.

 

Format: It is one of the following values:

• US - United States

• CA - Canada

• AU - Australia

 

The value of the country attribute must be compatible with the value of the locale attribute.

Since 2.0

logoUrl

(Optional) Absolute secure (HTTPS) URL path to the logo to display in the Visa Checkout lightbox; otherwise, the default Visa Checkout logo appears.

 

Your image must not exceed 174 pixels in width and should be 34 pixels high; oversize logos will be scaled to fit.

 

Format: HTTPS URL; maximum 256 characters

Since 2.0

displayName

(Optional) The merchant's name as it appears on the Review panel of the lightbox; typically, it is the name of your company.

 

Format: Alphanumeric

Since 2.0

websiteUrl

(Optional) Complete URL to your website.

 

Format: Valid URL, beginning with HTTP

Since 2.0

customerSupportUrl

(Optional) Your complete customer service or support URL.

 

Format: Valid URL, beginning with HTTP

Since 2.0

shipping

(Optional) Shipping properties associated with the lightbox; see .

 

Format: shipping

Since 2.0

review

(Optional) Review properties associated with the lightbox; see .

 

Format: review

Since 2.0

payment

(Optional) Payment method properties associated with the lightbox; see .

Format: payment

Since 2.0

dataLevel

(Optional) Whether the payment.success event response should include summary information or full information. Permission to receive full information must be configured in Visa Checkout; otherwise, you will always receive only summary information, regardless of the data value you specify.

 

Format: It is one of the following values:

• SUMMARY - Summary information (default)

• FULL - Full information, which is only available if you are configured to receive it

Since 2.0

 

 

Lightbox Panel Configuration Example

You can customize the appearance of lightbox panels, including the language in which text appears, whether the confirmation button is Continue or Pay, and various other messages and ornaments:

V.init({

...

settings: {

locale: "en_US",

countryCode: "US",

displayName: "MegaCorp",

logoUrl: "www.Some_Image_URL.gif",

websiteUrl: "www.MegaCorp.com",

customerSupportUrl: "www.MegaCorp.support.com",

...

dataLevel: "FULL"

...

);

 

Shipping Properties

Property

Description

acceptedRegions

(Optional) Override value for shipping region country codes in the merchant's external profile, which limits selection of eligible addresses in the consumer's account.

 

Format: A list of ISO-3166-1 alpha-2 standard codes, such as US or CA.

Since 2.0

collectShipping

(Optional) Whether to obtain a shipping address from the consumer.

 

Format: One of the following values:

• true - Obtain shipping address (default)

• false - Shipping address is not required

Since 2.0

 

Shipping Options Configuration Example

You can specify whether the consumer can set the shipping address (collectShipping) and the regions to which you ship:

V.init({

...

settings: {

...

shipping: {

acceptedRegions: ["US", "CA"],

collectShipping: "true"

},

...

);

 

 

Review Properties

Property

Description

message

(Optional) Your message to display on the Review page. You are responsible for translating the message (if required)

 

Format: Alphanumeric; maximum 120 characters

Since 2.0

buttonAction

(Optional) The button label in the Visa Checkout lightbox.

 

Format: One of the following values:

• Continue - Display Continue on the lightbox button (default)

• Pay - Display Pay on the lightbox button Note: A value for total must be specified; otherwise Continue will be displayed.

Since 2.0

 

 

Review Options Configuration Example

You can specify a message to display in the Visa Checkout lightbox and control the button text:

review: {

message: "Merchant defined message",

buttonAction: "Continue"

},

 

Payment Properties

Property

Description

cardBrands

(Optional) Card brands that are accepted.

 

Format: Array containing one or more of the following brands:

• VISA

• MASTERCARD

• AMEX

• DISCOVER

Since 2.0

acceptCanadianVisaDebit

(Optional) Override of whether a Canadian merchant accepts Visa Canada debit cards; ignored for non-Canadian merchants.

 

Format: One of the following values:

• true - Visa Canada debit cards accepted

• false - Visa Canada debit cards not accepted

 

Example: acceptCanadianVisaDebit : "true"

Since 2.0

 

 

Payment Options Configuration Example

You can limit the kind of cards you accept:

V.init({

...

settings: {

...

payment: {

cardBrands: [

"VISA",

"MASTERCARD"],

acceptCanadianVisaDebit : "true"

},

...

},

...

);

 

 

Payment Request Properties

Property

Description

merchantRequestId

(Optional) Merchant's ID associated with the request. Visa Checkout stores this value for your use as a convenience.

 

Format: Alphanumeric; maximum 100 characters

Since 2.0

currencyCode

(Required) The currency with which to process the transaction.

 

Format: It is one of the following ISO 4217 standard alpha-3 code values:

• USD - US dollars

• CAD - Canadian dollars

• AUD - Australian dollars

Currency codes must be uppercase.

 

Example: "currencyCode" : "USD"

Since 2.0

subtotal

(Required) Subtotal of the payment.

 

Format: Numeric; maximum 7 digits with optional decimal point and 2 decimal digits

 

Example: "subtotal" : "9.00"

Since 2.0

shippingHandling

(Optional) Total of shipping and handling charges in the payment.

 

Format: Numeric; maximum 7 digits with optional decimal point and 2 decimal digits

 

Example: "shippingHandling" : "3.00"

Since 2.0

tax

(Optional) Total tax-related charges in the payment.

 

Format: Numeric; maximum 7 digits with optional decimal point and 2 decimal digits

 

Example: "tax" : "1.00"

Since 2.0

discount

(Optional) Total of discounts related to the payment. If provided, it is a positive value representing the amount to be deducted from the total.

 

Format: Numeric; maximum 7 digits with optional decimal point and 2 decimal digits

 

Example: "discount" : "2.50"

Since 2.0

giftWrap

(Optional) Total gift-wrapping charges in the payment.

 

Format: Numeric; maximum 7 digits with optional decimal point and 2 decimal digits

 

Example: "giftWrap" : "1.99"

Since 2.0

misc

(Optional) Total uncategorized charges in the payment.

 

Format: Numeric; maximum 20 digits, including an optional decimal point.

 

Example: "misc" : "1.00"

Since 2.0

total

(Optional) Total of the payment including all amounts.

 

Format: Numeric; maximum 7 digits with optional decimal point and 2 decimal digits

 

Example: "total" : "9.00"

Since 2.0

orderId

(Optional) Merchant's order ID associated with the payment.

Format: Alphanumeric; maximum 100 characters

Since 2.0

promoCode

(Optional) Promotion codes associated with the payment. Multiple promotion codes are separated by a period ( . ).

 

Format: Alphanumeric; maximum 100 characters

 

Example: promoCode: "ABC"."DEF"."XYZ"

Since 2.0

customData

(Optional) Merchant-supplied data, as name-value pairs.

 

Format: Alphanumeric; maximum 1024 characters

 

Example:

customData: {

"nvPair": [

{ "name": "Name1", "value": "value1" },

{ "name": "Name2", "value": "value2" }

] ...

 

Since 2.0

 

Note: The sandbox sets specific risk advice and score values based on the subTotal of the transaction in the request. The risk information is returned in the consumer information payload (encPaymentData) of a successful response.

Value of the transaction (USD only)

Value of advice in the response

Value of score in the response

0.01 to 0.99

Note: Amounts between 0.01 and 0.89 cause the transaction to be declined.

UNAVAILABLE

0

1.00 to 49.99

LOW

10

50.00 to 149.99

MEDIUM

45

150.00 or more

HIGH

90

 

Payment Request Configuration Example

You specify the payment request for which the consumer is being asked to agree:

V.init({

...

paymentRequest: {

merchantRequestId: "Merchant defined request ID",

currencyCode: "USD",

subtotal: "10.00",

shippingHandling: "2.00",

tax: "2.00",

discount: "1.00",

giftWrap: "2.00",

misc: "1.00",

total: "16.00",

description: "Megacorp Product",

orderId: "Merchant defined order ID",

promoCode: "Merchant defined promo code",

customData: {

"nvPair": [

{ "name": "customName1", "value": "customValue1" },

{ "name": "customName2", "value": "customValue2" }

]

...

);

 

 

Response to Payment Success Events

The response associated with the payment.success event returns the following information:

Property

Description

callId

Visa Checkout transaction ID, which represents the purchase.

 

Format: Numeric; maximum 20 digits

 

Example: "callId":"..."

Since 2.0

responseStatus

Response status.

 

 

 

encKey

Encrypted key to be used to decrypt encPaymentData. You use your shared secret to decrypt this key.

 

Format: Alphanumeric; maximum 128 characters

 

Example: "encKey":"..."

Since 2.0

encPaymentData

Encrypted consumer and payment data that can be used to process the transaction. You decrypt this by first unwrapping the encKey value, then using that unwrapped key to decrypt this value.

 

Format: Alphanumeric; maximum 1024 characters

 

Example: "encPaymentData":"..."

Since 2.0

externalClientId

Merchant ID of the merchant receiving the payment.

 

Format: Alphanumeric; maximum 100 characters

Since 2.0

partialShippingAddress

Partial shipping address of the consumer.

 

Format: Partial shipping address structure

Since 2.0

 

 

Response Status

Property

Description

status

HTTPS response status.

 

Format: Numeric

Since 2.0

code

Internal subcode.

 

Format: Numeric

Since 2.0

severity

Severity of the error.

 

Format: It is one of the following values:

• ERROR

• WARNING

Since 2.0

message

Description of the error.

 

Format: Alphanumeric

Since 2.0

 

 

Partial Shipping Address

Property

Description

countryCode

Country code of the country where the purchase should be shipped, such as US; useful for calculating shipping costs.

 

Format: Alphanumeric; maximum 2 characters

Since 2.0

postalCode

Postal code of the location where the purchase should be shipped, if available; useful for calculating shipping costs.

 

Format: Alphanumeric; maximum 128 characters

Since 2.0

 

 

Response to Payment Cancelled Events

Property

Description

callId

Visa Checkout transaction ID, which represents the cancelled payment.

 

Example: "callId":"..."

Since 2.0

 

 

Response to Error Events

Property

Description

status

HTTPS response status.

 

Format: Numeric

Since 2.0

code

Internal subcode.

 

Format: Numeric

Since 2.0

severity

Severity of the error.

 

Format: It is one of the following values:

• ERROR

• WARNING

Since 2.0

message

Description of the error.

 

Format: Alphanumeric

Since 2.0

 

Example

{

"responseStatus" : { "status" : 404,

"code" : "1010",

"severity" : "ERROR",

"message" : "CallId b9346ed5-08d1-44b2-be32-bbde5c4bf34f was not found."

}}

 

Optimizing the Checkout Flow for Mobile Browsers

Visa Checkout is optimized for mobile browsers even if your checkout flow is not. Support is provided for both iOS and Android devices. In order to allow for a mobile optimized Visa Checkout experience, add the following <meta> tag to your HTML <head> block:

<html>

<head>

...

<meta name="viewport"

content="width=device-width, initial-scale=1.0, maximum-scale=1.0,

user-scalable=no" />

...

</head>

 

Complete Web Page HTML Example

You initialize the Visa Checkout library in the V.init event handler of your onVisaCheckoutReady function with properties that identify the merchant implementing the button, button characteristics and settings related to the behavior of the lightbox, and payment request properties. You specify how to respond to events related to the lightbox closing and the payment request in V.on event handlers.

 

Note: You must provide your Visa Checkout API key when initializing the Visa Checkout JavaScript library.

The following example shows an HTML web page that loads the Visa Checkout library, defines handlers for initialization and payment events, and creates a Visa Checkout button:

 

<html>

<head>

<script type="text/javascript">

function onVisaCheckoutReady() {

V.init({

apikey: "...",

sourceId: "Merchant Defined Source ID",

settings: {

locale: "en_US",

countryCode: "US",

displayName: "...Corp",

logoUrl: "www.Some_Image_URL.gif",

websiteUrl: "www....Corp.com",

customerSupportUrl: "www....Corp.support.com",

shipping: {

acceptedRegions: ["US", "CA"],

collectShipping: "true"

},

payment: {

cardBrands: [

"VISA",

"MASTERCARD"],

acceptCanadianVisaDebit: "true"

},

review: {

message: "Merchant defined message",

buttonAction: "Continue"

},

dataLevel: "SUMMARY"

},

paymentRequest: {

merchantRequestId: "Merchant defined request ID",

currencyCode: "USD",

subtotal: "10.00",

shippingHandling: "2.00",

tax: "2.00",

discount: "1.00",

giftWrap: "2.00",

misc: "1.00",

total: "16.00",

description: "Megacorp Product",

orderId: "Merchant defined order ID",

promoCode: "Merchant defined promo code",

customData: {

"nvPair": [

{ "name": "customName1", "value": "customValue1" },

{ "name": "customName2", "value": "customValue2" }

]

}

}

}

);

V.on("payment.success", function(payment){document.write(JSON.stringify(payment)); });

V.on("payment.cancel", function (payment) { ... });

V.on("payment.error", function (payment, error) { ... });

}

</script>

</head>

<body>

<img alt="Visa Checkout" class="v-button" role="button"

src="https://sandbox.secure.checkout.visa.com/wallet-services-web/xo/button.png?

cardBrands=VISA,MASTERCARD,DISCOVER,AMEX"/>

<script type="text/javascript"

src="https://sandbox-assets.secure.checkout.visa.com/

checkout-widget/resources/js/integration/v1/sdk.js">

</script>

</body>

</html>

 

Clickjacking Prevention

Clickjacking Prevention Steps

To prevent clickjacking of your pages, each page must contain JavaScript to verify that there are no transparent layers, such as might be the case if your page was loaded as an iFrame of a page containing malicious code, and that only your site can load your pages.

 

Checking for Hidden Layers

Pages that prevent clickjacking contain JavaScript, such as the following, to verify that there are no transparent layers in which malicious code could reside:

 

<head>

...

<style id=”antiClickjack”>body{display:none;}</style>

<script type=”text/javascript”>

if (self === top) {

var antiClickjack = document.getElementById(“antiClickjack”);

antiClickjack.parentNode.removeChild(antiClickjack);

} else {

top.location = self.location;

}

</script>

...

</head>

 

Using the X-Options Header

Messages directed at your pages must include an X-FRAME-OPTIONS header to verify that the response is known to be from your web application:

 

  • X-FRAME-OPTIONS DENY prevents anything from framing your page.
  • X-FRAME-OPTIONS SAMEORIGIN prevents anything except your application from framing your page.

 

Testing Your Clickjacking Prevention Implementation

 

To test your implementation of anti-clickjacking measures:

Note: These steps assume your site is not already in an iFrame.

 

  1. Install or use a test server that is not being used for your production or sandbox site and does not contain the pages that you want to test. For example, you can test using Tomcat on localhost:8080.
  1. Create a page on your test server that loads the page containing the Visa Checkout button in an iFrame.

 

<html>

<body>

<iframe src="https://www.yoursite.com/..." width=100% height=100%>

<p>Your browser does not support iframes.</p>

</iframe>

</body>

</html>

 

  1. Test the page you created to load your actual page in an iFrame. Your test page should either be blank or display a message, such as The content cannot be displayed in a frame.

 

If you can see the page that contains the Visa Checkout button, your prevention measures are not sufficient.

As a best practice, you should automate these steps so that you automatically run a script to test your clickjacking prevention measures whenever you change or add a page to your site.

 

Example Server-Side Clickjacking Prevention Implementation

The following example shows how to implement X-FRAME-OPTIONS DENY or X-FRAME-OPTIONS SAMEORIGIN headers in a Java servlet for pages served by Tomcat:

 

Java Servlet

The following sample implements a servlet to provide either the X-FRAME-OPTIONS DENY header or the X-FRAME-OPTIONS SAMEORIGIN header as a filter:

 

package com.your_package.filters;

import java.io.IOException;

import javax.servlet.Filter;

import javax.servlet.FilterChain;

import javax.servlet.FilterConfig;

import javax.servlet.ServletException;

import javax.servlet.ServletRequest;

import javax.servlet.ServletResponse;

import javax.servlet.http.HttpServletResponse;

public class ClickjackFilter implements Filter

{

private String mode = “DENY”;

public void doFilter(ServletRequest request, ServletResponse response,

FilterChain chain) throws IOException, ServletException {

HttpServletResponse res = (HttpServletResponse)response;

chain.doFilter(request, response);

res.addHeader(“X-FRAME-OPTIONS”, mode );

}

public void destroy() {

}

public void init(FilterConfig filterConfig) {

String configMode = filterConfig.getInitParameter(“mode”);

if ( configMode != null ) {

mode = configMode;

}

}

}

 

List of supported Visa Checkout Transaction Types

  • authorization
  • capture
  • refund
  • void

 

All Visa Checkout transaction types are submitted through the standard Payeezy Gateway Web Service API endpoints ().

 

Authorization Transaction

Notes:

  • The Visa Checkout Call ID is required in the request
  • No payment details are passed in the request
  • Masked card information, customer address, and transaction amount are obtained from Visa Checkout and are included in response

 

Request

{"transaction_type":"01","visa_checkout":{"call_id":"5467428919436032412"}}

 

Response

{

"merchant_url": "http://www.firstdata-demo-account.com",

"merchant_address": "3393 Peachtree Road NE",

"bank_message": "Approved",

"partial_redemption": 0,

"transaction_approved": 1,

"cc_number": "############1111",

"bank_resp_code": "100",

"address": {

"zip": "90210",

"country_code": "US",

"address1": "21 Jump Street",

"city": "Beverley Hills",

"state": "CA",

"phone_number": "2122524000"

},

"currency_code": "CAD",

"avs": "2",

"transaction_error": 0,

"exact_resp_code": "00",

"exact_message": "Transaction Normal",

"client_ip": "127.0.0.1",

"transaction_type": "01",

"merchant_country": "United States",

"gateway_id": "AD0160-01",

"cc_expiry": "1016",

"sequence_no": "000005",

"merchant_postal": "30342",

"visa_checkout": {

"call_id": "5467428919436032412"

},

"cvd_presence_ind": 0,

"merchant_city": "Atlanta",

"cardholder_name": "Timothy Duncan",

"credit_card_type": "Visa",

"retrieval_ref_no": "7526387",

"transaction_tag": 5273,

"ctr": "=========== TRANSACTION RECORD ==========\nSettlement - First Data Testing 002\n3393 Peachtree Road NE\nAtlanta, GA 30342\nUnited States\nhttp://www.firstdata-demo-account.com\n\nTYPE: Pre-Authorization\n\nACCT: Visa $ 1,036.26 CAD\n\nCARDHOLDER NAME : Timothy Duncan \nCARD NUMBER : ############1111\nDATE/TIME : 10 Dec 14 12:20:26\nREFERENCE # : 000005 M\nAUTHOR. # : ET187971\nTRANS. REF. : \n\n Approved - Thank You 100\n\nSIGNATURE\n\n\n\n\n------------------------------------\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to card\nissuer pursuant to cardholder agreement.\n=========================================",

"cvv2": "I",

"merchant_province": "Georgia",

"client_email": " Timothy.Duncan @email.com",

"merchant_name": "Settlement - First Data Testing 002",

"authorization_num": "ET187971",

"amount": 1036.26

}

 

Capture Transaction – Capture of a previous Authorization

Notes

  • The Visa Checkout Call ID is not passed in the request. Instead, the previous authorization transaction is identified by transaction_tag and authorization_num, which are required in the request
  • The Visa Checkout Call ID is obtained from the original transaction and included in the response

 

Request

{"transaction_type":"32","amount":1036.26,"transaction_tag": 5273,"authorization_num":"ET187971"}

 

Response

{

"merchant_postal": "30342",

"transaction_type": "32",

"amount": 1036.26,

"ctr": "=========== TRANSACTION RECORD ==========\nSettlement - First Data Testing 002\n3393 Peachtree Road NE\nAtlanta, GA 30342\nUnited States\nhttp://www.firstdata-demo-account.com\n\nTYPE: Completion\n\nACCT: Visa $ 1,036.26 CAD\n\nCARDHOLDER NAME : Donncha Redmond\nCARD NUMBER : ############1111\nDATE/TIME : 10 Dec 14 12:24:17\nREFERENCE # : 000005 M\nAUTHOR. # : ET191879\nTRANS. REF. : \n\n Approved - Thank You 100\n\nSIGNATURE\n\n\n\n\n------------------------------------\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to card\nissuer pursuant to cardholder agreement.\n=========================================",

"transaction_tag": 5274,

"retrieval_ref_no": "2655088",

"bank_message": "Approved",

"exact_resp_code": "00",

"cvv2": "I",

"merchant_address": "3393 Peachtree Road NE",

"currency_code": "CAD",

"visa_checkout": {

"call_id": "5467428919436032412"

},

"merchant_city": "Atlanta",

"cc_number": "############1111",

"partial_redemption": 0,

"transaction_approved": 1,

"merchant_name": "Settlement - First Data Testing 002",

"merchant_country": "United States",

"authorization_num": "ET191879",

"gateway_id": "AD0160-01",

"bank_resp_code": "100",

"cardholder_name": "Timothy Duncan",

"credit_card_type": "Visa",

"cc_expiry": "1016",

"cvd_presence_ind": 0,

"sequence_no": "000005",

"merchant_url": "http://www.firstdata-demo-account.com",

"merchant_province": "Georgia",

"transaction_error": 0,

"exact_message": "Transaction Normal",

"client_ip": "127.0.0.1"

}

 

Refund Transaction – Refund of a previous Capture Transaction

Notes

  • The Visa Checkout CallID is not passed in the request. Instead, the previous captured transaction is identified by transaction_tag and authorization_num, which are required in the request
  • The Visa Checkout CallID is obtained from the original transaction and included in the response

 

Request

{"transaction_type":"34","amount":500.34,"transaction_tag": 5274,"authorization_num":"ET191879"}

 

Response

{

"merchant_postal": "30342",

"transaction_type": "34",

"amount": 500.34,

"ctr": "=========== TRANSACTION RECORD ==========\nSettlement - First Data Testing 002\n3393 Peachtree Road NE\nAtlanta, GA 30342\nUnited States\nhttp://www.firstdata-demo-account.com\n\nTYPE: Refund\n\nACCT: Visa $ 500.34 CAD\n\nCARDHOLDER NAME : Donncha Redmond\nCARD NUMBER : ############1111\nDATE/TIME : 10 Dec 14 12:26:39\nREFERENCE # : 000006 M\nAUTHOR. # : ET165885\nTRANS. REF. : \n\n Approved - Thank You 100\n\nSIGNATURE\n\n\n\n\n------------------------------------\n\nPlease retain this copy for your records.\n\n=========================================",

"transaction_tag": 5275,

"retrieval_ref_no": "7769505",

"bank_message": "Approved",

"exact_resp_code": "00",

"cvv2": "I",

"merchant_address": "3393 Peachtree Road NE",

"currency_code": "CAD",

"visa_checkout": {

"call_id": "5467428919436032412"

},

"merchant_city": "Atlanta",

"cc_number": "############1111",

"partial_redemption": 0,

"transaction_approved": 1,

"merchant_name": "Settlement - First Data Testing 002",

"merchant_country": "United States",

"authorization_num": "ET165885",

"gateway_id": "AD0160-01",

"bank_resp_code": "100",

"cardholder_name": "Timothy Duncan",

"credit_card_type": "Visa",

"cc_expiry": "1016",

"cvd_presence_ind": 0,

"sequence_no": "000006",

"merchant_url": "http://www.firstdata-demo-account.com",

"merchant_province": "Georgia",

"transaction_error": 0,

"exact_message": "Transaction Normal",

"client_ip": "127.0.0.1"

}

 

Void Transaction – Void of a previous Refund Transaction

Notes

  • The Visa Checkout Call ID is not passed in the request. Instead, the previous refund transaction is identified by transaction_tag and authorization_num, which are required in the request
  • The Visa Checkout Call ID is obtained from the original transaction and included in the response

 

Request

{"transaction_type":"33","amount":500.34,"transaction_tag": 5275,"authorization_num":"ET165885"}

 

Response

{

"merchant_postal": "30342",

"transaction_type": "33",

"amount": 500.34,

"ctr": "=========== TRANSACTION RECORD ==========\nSettlement - First Data Testing 002\n3393 Peachtree Road NE\nAtlanta, GA 30342\nUnited States\nhttp://www.firstdata-demo-account.com\n\nTYPE: Void\n\nACCT: Visa $ 500.34 CAD\n\nCARDHOLDER NAME : Donncha Redmond\nCARD NUMBER : ############1111\nDATE/TIME : 10 Dec 14 12:27:11\nREFERENCE # : 000006 M\nAUTHOR. # : ET149705\nTRANS. REF. : \n\n Approved - Thank You 100\n\nSIGNATURE\n\n\n\n\n------------------------------------\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to card\nissuer pursuant to cardholder agreement.\n=========================================",

"transaction_tag": 5276,

"retrieval_ref_no": "0139961",

"bank_message": "Approved",

"exact_resp_code": "00",

"cvv2": "I",

"merchant_address": "3393 Peachtree Road NE",

"currency_code": "CAD",

"visa_checkout": {

"call_id": "5467428919436032412"

},

"merchant_city": "Atlanta",

"cc_number": "############1111",

"partial_redemption": 0,

"transaction_approved": 1,

"merchant_name": "Settlement - First Data Testing 002",

"merchant_country": "United States",

"authorization_num": "ET149705",

"gateway_id": "AD0160-01",

"bank_resp_code": "100",

"cardholder_name": "Timothy Duncan",

"credit_card_type": "Visa",

"cc_expiry": "1016",

"cvd_presence_ind": 0,

"sequence_no": "000006",

"merchant_url": "http://www.firstdata-demo-account.com",

"merchant_province": "Georgia",

"transaction_error": 0,

"exact_message": "Transaction Normal",

"client_ip": "127.0.0.1"

}

 

 

3.7 Debit Bill Pay

For full feature description please refer to the following URL: https://support.payeezy.com/hc/en-us/articles/212571807

The API v9 and higher supports Debit Bill Pay service. In order to use HMAC, please use API v12 and higher.

 

Debit Bill Pay Transaction Sample:

Requesting a Debit Bill Pay transaction should follow similar structure to Credit Card transactions. The only difference is specifying the Credit_Card_Type property as "Debit Bill Pay". You will notice in the Response that "credit_card_type" property will be updated to the Debit Network name the request was processed through.

Please see  format samples below.

 

Request Sample (JSON):

 "Transaction": {

   "ExactID": "XXXXXXXX",

   "Password": "XXXXXXXX",

   "Card_Number": "XXXXXXXXXXXXX",

   "Transaction_Type": "00",

   "DollarAmount": "50",

   "Expiry_Date": "1017",

   "CardHoldersName": "Happy Customer",

   "CardType": "Debit Bill Pay",

   "Currency_Code": "USD"

 }

 

Request Sample (XML):

<?xml version="1.0" encoding="UTF-8"?>

<Transaction>

<ExactID>XXXXXXXX</ExactID>

<Password>XXXXXXXXX</Password>

<Card_Number>XXXXXXXXXXXXXXXX</Card_Number>

<Transaction_Type>00</Transaction_Type>

<DollarAmount>50</DollarAmount>

<Expiry_Date>1018</Expiry_Date>

<CardHoldersName>Happy Customer</CardHoldersName>

<CardType>Debit Bill Pay</CardType>

<Currency_Code>USD</Currency_Code>

</Transaction>

  

Response Sample (JSON):

"TransactionResult": {
},
"ExactID": "XXXXXXXXXXX",
"Transaction_Type": "00",
"DollarAmount": "50.0",
"Card_Number": "XXXXXXXXXXXXXX",
"Transaction_Tag": "XXXXXXXX",
"Authorization_Num": "XXXXXXX",
"Expiry_Date": "0817",
"CardHoldersName": "Happy Customer",
"CVD_Presence_Ind": "0",
"Transaction_Error": "false",
"Transaction_Approved": "true",
"EXact_Resp_Code": "00",
"EXact_Message": "Transaction Normal",
"Bank_Resp_Code": "100",
"Bank_Message": "Approved",
"SequenceNo": "XXXXXXX",
"Retrieval_Ref_No": "XXXXXXX",
"Currency": "USD",
"AmountRequested": "0.0",
"PartialRedemption": "false",
"MerchantName": "XXXXXXXXX",
"MerchantProvince": "XXXXXXX",
"MerchantCountry": "XXXXXXXX",
"CardType": "Debit Bill Pay",
"VirtualCard": "false"
}

 

 

Response Sample (XML):

<?xml version="1.0" encoding="UTF-8" ?>

<TransactionResult>

<ExactID>XXXXXXXXX</ExactID>

<Password/>

<Transaction_Type>00</Transaction_Type>

<DollarAmount>50.0</DollarAmount>

<SurchargeAmount/>

<Card_Number>XXXXXXXXXXXXXXXXXX</Card_Number>

<Transaction_Tag>4883300</Transaction_Tag>

<Track1/>

<Track2/>

<PAN/>

<Authorization_Num>332932</Authorization_Num>

<Expiry_Date>0918</Expiry_Date>

<CardHoldersName>Happy Customer</CardHoldersName>

<VerificationStr1/>

<VerificationStr2/>

<CVD_Presence_Ind>0</CVD_Presence_Ind>

<ZipCode/>

<Tax1Amount/>

<Tax1Number/>

<Tax2Amount/>

<Tax2Number/>

<Secure_AuthRequired/>

<Secure_AuthResult/>

<Ecommerce_Flag/>

<XID/>

<CAVV/>

<CAVV_Algorithm/>

<Reference_No/>

<Customer_Ref/>

<Reference_3/>

<Language/>

<Client_IP/>

<Client_Email/>

<User_Name/>

<Transaction_Error>false</Transaction_Error>

<Transaction_Approved>true</Transaction_Approved>

<EXact_Resp_Code>00</EXact_Resp_Code>

<EXact_Message>Transaction Normal</EXact_Message>

<Bank_Resp_Code>100</Bank_Resp_Code>

<Bank_Message>Approved</Bank_Message>

<Bank_Resp_Code_2/>

<SequenceNo>0200862</SequenceNo>

<AVS/>

<CVV2/>

<Retrieval_Ref_No>151014</Retrieval_Ref_No>

<CAVV_Response/>

<Currency>USD</Currency>

<AmountRequested>0.0</AmountRequested>

<PartialRedemption>false</PartialRedemption>

<MerchantName>XXXXXXXXXXXX</MerchantName>

<MerchantAddress/>

<MerchantCity/>

<MerchantProvince>XXXXXXX</MerchantProvince>

<MerchantCountry>XXXXXXXX</MerchantCountry>

<MerchantPostal/>

<MerchantURL/>

<TransarmorToken/>

<CardType>Debit Bill Pay</CardType>

<CurrentBalance/>

<PreviousBalance/>

<EAN/>

<CardCost/>

<VirtualCard>false</VirtualCard>

<CTR>

 

NOTE: A Debit Bill Pay Refund and Void request works in similar way as a Credit Card Refund and Void. One important difference: Debit Bill Pay void can only be performed within a 90 minute window.  After that a refund must be completed, instead of a void. Click here to see Credit Card request samples.

 

 

3.8 Special Payment Transactions

The API v21 and higher supports the Special Payment feature. 

 

Special Payment Transaction Sample:

Requesting a Special Payment transaction should follow similar structure to the regular Credit Card transactions.

The differences that is present compared to a regular credit card transactions: to process a Special Payment, there is a need to use the optional "special_payment" flag. 

Field name Data Type Request Values  Response Values

special_payment (JSON) 

SpecialPayment (XML)

(API v21 and higher)

 String 
  • "B" to indicate a special payment
  • All other values will be ignored; in such case a regular credit card transaction will be processed.
  • "approved"
  • "declined"
  • "not processed" (When an error occurs during an authorization request to a Special Payment initial authorization OR for any recurring authorization request OR when the flag is used for payment types that don't support Special Payment)

 

Special Payment flag works for Visa transactions only. If Special Payments are enabled on a terminal and the special_payment flag is used for a Visa transaction, then the transaction will be processed as Special Payment. If the terminal is not enabled for Special Payments, the flag will be ignored and the transaction will be processed as a regular credit card transaction.

If the flag is used for other credit card brands, it will be ignored and the transaction will be processed as a regular credit card transaction.

 

API Request sample (JSON):

{
"gateway_id": "XX1234-12",
"password": "XXXXXXXX",
"transaction_type":"01",
"cc_number":"4111111111111111",
"cardholder_name": "John Snow",
"cc_expiry":"1020",
"amount":"100.25",
"special_payment": "B"

 

API Response sample (JSON):

{
"transaction_error":0,
"transaction_approved":1,
"exact_resp_code":"00",
"exact_message":"Transaction Normal",
"bank_resp_code":"100",
"bank_message":"Approved",
"sequence_no":"000013",
"cvv2":"I",
"retrieval_ref_no":"6288297",
"merchant_name":"MerchantName",
"merchant_address":"123 Merchant street",
"merchant_city":"MerchantCity",
"merchant_province":"CA",
"merchant_country":"US",
"merchant_postal":"12345",
"merchant_url":"http://www.url.com",
"ctr":"========== TRANSACTION RECORD ==========\nMerchantName\n 123 Merchant street way\nMerchantCity, CA 12345\nUS\nhttp://www.url.com\n\nTYPE: Pre-Authorization\n\nACCT: Visa $ 100.25 USD\n\nCARDHOLDER NAME : John Snow\nCARD NUMBER : ############1111\nDATE/TIME : 18 Aug 16 15:04:06\nREFERENCE # : 001 000013 M\nAUTHOR. # : XP174346\nTRANS. REF. : \n\n Approved - Thank You 100\n\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================",
"gateway_id":"XX1234-12",
"transaction_type":"01",
"amount":100.25,
"cc_number":"############1111",
"transaction_tag":1234567890123,
"authorization_num":"XP123456",
"cc_expiry":"1020",
"cardholder_name":"John Snow",
"cvd_presence_ind":0,
"currency_code":"USD",
"partial_redemption":0,
"credit_card_type":"Visa",
"special_payment":"approved"
}

 

3.9 Wallet Provider ID

Please use this field to differentiate between the digital wallet providers. This feature is supported by API version 22 and higher.

If a digital wallet was used during a transaction, then Wallet Provider ID must be specified. Without this info a transaction will be incorrectly identified as a 3D Secure transaction. (If a 3D Secure transaction is processed, there is no Wallet Provider and hence no need to populate the wallet_provider_id field)

If the API field is not populated, Payeezy Gateway will default to value=1 (no wallet provider) 

 

Field name Data Type Request Values  Response Values

wallet_provider_id (JSON) 

WalletProviderID  (XML)

(API v22 and higher )

 String

(optional) 

  • 1- default; no wallet
    2- Visa Checkout
    3- MasterPass
    4- Apple Pay
    5- Samsung Pay
    6- Android Pay
  • No response returned inside this field

 

API Request example (JSON):

{
"gateway_id": "A04733-01",
"password": "4apitest",
"transaction_type": "00",
"amount": "10",
"cc_number": "373953192351004",
"cardholder_name": "Jonny Step",
"wallet_provider_id": "4",
"cc_expiry": "0920"
}

 

API Response example (JSON):

{"transaction_error":0,
"transaction_approved":1,
"exact_resp_code":"00",
"exact_message":"Transaction Normal",
"bank_resp_code":"100",
"bank_message":"Approved",
"sequence_no":"0226916",
"retrieval_ref_no":"170124",
"merchant_name":"ACME Water Co.",
"merchant_address":"12345 Main St",
"merchant_city":"Coral Springs",
"merchant_province":"Florida",
"merchant_country":"United States",
"merchant_postal":"33065",
"ctr":"========== TRANSACTION RECORD ==========\nACME Water Co.\n12345 Main St\nCoral Springs, FL 33065\nUnited States\n\n\nTYPE: Purchase\n\nACCT: American Express $ 10.00 USD\n\nCARDHOLDER NAME :Jonny Step\nCARD NUMBER : ###########1004\nDATE/TIME : 24 Jan 17 19:43:37\nREFERENCE # : 001 0226916 M\nAUTHOR. # : 989484\nTRANS. REF. : \n\n Approved - Thank You 100\n\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================",
"gateway_id”:”XXXXXX-01",
"transaction_type":"00",
"amount":10.0,
"cc_number":"###########1004",
"transaction_tag":6579819,
"authorization_num":"989484",
"cc_expiry":"0920",
"cardholder_name":"Jonny Step",
"cvd_presence_ind":0,
"currency_code":"USD",
"partial_redemption":0,
"credit_card_type":"American Express"}

 

4 Request Properties

Only some of the following properties are required, depending on the processing scenario being used. Refer to the Processing Scenarios section for more information on which properties are required for each particular scenario. The value for a property should be a string conforming to the data type (i.e. Null, String, Integer etc.) indicated below. Note that a small number of the parameters have different names when using the JSON format.

Character Encoding: Incoming parameters should be encoded in UTF-8, except where noted as ASCII, to ensure correct text display and processing.

Property

Description
ExactID
  • String [10]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
gateway_id (JSON format)
Identifies the location/terminal that is sending the transaction. This number is of the format Axxxxx-xx and is provided by First Data upon set-up. The ExactID must be accompanied by a password.
Password
  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
password (JSON format)
Minimum 8 digit alphanumeric password that is uniquely associated with each ExactID. This value must be kept as secure (and secret) as possible.
Transaction_Type
  • String [2]
  • {Read/Write} {minOccurs=”1” maxOccurs=”1”}

transaction_type (JSON format)

Populated with a two-digit string indicator. The indicator identifies the transaction type. Descriptions of these transaction types can be found here. Supported values include:
  • 00 = Purchase
  • 01 = Pre-Authorization
  • 02 = Pre-Authorization Completion
  • 03 = Forced Post
  • 04 = Refund
  • 05 = Pre-Authorization Only
  • 07 = PayPal Order
  • 13 = Void
  • 32 = Tagged Pre-Authorization Completion
  • 33 = Tagged Void
  • 34 = Tagged Refund
  • 83 = CashOut (ValueLink, v9 or higher end point only)
  • 85 = Activation (ValueLink, v9 or higher end point only)
  • 86 = Balance Inquiry (ValueLink, v9 or higher end point only)
  • 88 = Reload (ValueLink, v9 or higher end point only)
  • 89 = Deactivation (ValueLink, v9 or higher end point only)

 

DollarAmount
  • Double
  • {Read/Write} {minOccurs="0" maxOccurs="1"}
amount (JSON format)
For information on the highest dollar amounts allowed within Payeezy Gateway, please click here.
Card_Number
  • String [16]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cc_number (JSON format)
The customer’s credit card number. Not used for tagged transaction types.
Transaction_Tag
  • Unsigned Integer
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
transaction_tag (JSON format)

A unique identifier to associate with a tagged transaction. Only for tagged transaction types. Maximum Length is 10 Digits.

Track1
  • String [75]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
track1 (JSON format)
Populated with the unmodified track 1 data swiped from a valid credit card. Start and end sentinels should not be included. Only for swiped transactions.
Track2
  • String
  • {Read/Write } {minOccurs=”0” maxOccurs=”1”}
track2 (JSON format)
Populated with the unmodified track 2 data swiped from a valid credit card. Start and end sentinels should not be included. Only for swiped transactions.
Authorization_Num
  • String [8]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
authorization_num (JSON format)
This is the authorization number returned by the cardholder’s financial institution when a transaction has been approved. This value needs to be sent when sending various transaction types such as preauthorization completion, void, or tagged transaction.
Expiry_Date
  • String [4]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cc_expiry (JSON format)
The credit card expiry date in the format mmyy. Property for manually entering expiry date. If Track1 or Track2 is populated, there is no need to set this field.
CardHoldersName
  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cardholder_name (JSON format)

The customer’s name. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).

Required Character Format is ASCII.

VerificationStr1
  • String [41]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cc_verification_str1 (JSON format)

This string is populated with the cardholders address information in a specific format. The address is verified and a result is returned (AVS property) that indicates how well the address matched.

VerificationStr1 is comprised of the following constituent address values: Street, Zip/Postal Code, City, State/Province, Country. They are separated by the Pipe Character "|".

Street Address|Zip/Postal|City|State/Prov|Country

Required Character Format is ASCII.

Note: not supported after endpoint v13. Use the Address element from v14 onwards (see Section 4.1)

VerificationStr2
  • String [4]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cc_verification_str2 (JSON format)

This is the 0, 3, or 4-digit code on the back of the credit card sometimes called the CVV2 or CVD value.

Note: not supported after endpoint v13. Use the CVDCode element below.

CVDCode
  • String [4]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cvd_code (JSON format)
This is the 0, 3, or 4-digit code on the back of the credit card sometimes called the CVV2 or CVD value.
CVD_Presence_Ind
  • String [1]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cvd_presence_ind (JSON format)
The number indicates how the CVV2 value should be handled when processing. The value must be either null or the integer 0, 1, 2, or 9. Note that null defaults to 0.
  • Null or 0 = Not Supported (Default)
  • 1 = Value provided by Cardholder
  • 2 = Value provided on card is Illegible
  • 9 = Cardholder states data is not available
Reference_No
  • String [20]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
reference_no (JSON format)

A merchant defined value that can be used to internally identify the transaction. This value is passed through to the Payeezy Gateway unmodified, and may be searched in First Data Payeezy Gateway Real-time Payment Manager (RPM). It is not passed on to the financial institution. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).

NOTE: For non-international transactions, DO NOT USE the following characters: pipe (|), caret (^), percent symbol (%), backslash (\), or forward slash (/).

For international transactions DO NOT USE the following punctuation: caret (^), backslash (\), openbracket ([), closed bracket (]), tilde (~) or accent key (`). If used the transaction will reject for Response Reason Code 225 (Invalid field data)

For two stage transactions (pre-auth/completion), the reference number utilized at the time of pre-authorization will be utilized at
time of transaction completion. An override of this value is not supported. The consistent usage of values enables a merchant to achieve the best interchange rates and least re-authorizations. Typically, the reference number field is the purchase order number or unique sequence value associated to a given transaction suite.

ZipCode
  • String [10]
  • {Write} {minOccurs=”0” maxOccurs=”1”}
zip_code (JSON format)

Customer zip code used for qualifying transactions, only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. Payeezy Gateway supports Level II processing for Visa, MasterCard and American Express, and Level III processing for Visa and MasterCard.

Tax1Amount
  • Double [99,999.99]
  • {Write} {minOccurs=”0” maxOccurs=”1”}
tax1_amount (JSON format)

Tax value included in total amount, only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the PST amount.

Payeezy Gateway supports Level II processing for Visa, MasterCard and American Express, and Level III processing for Visa and MasterCard.

Tax1Number
  • String [20]
  • {Write} {minOccurs=”0” maxOccurs=”1”}
tax1_number (JSON format)

Registered number associated with the tax value. Used for reference or government claims purposes and only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the PST number.

Payeezy Gateway supports Level II processing for Visa, MasterCard and American Express, and Level III processing for Visa and MasterCard.

Tax2Amount
  • Double [99,999.99]
  • {Write} {minOccurs=”0” maxOccurs=”1”}
tax2_amount (JSON format)

Tax value included in total amount, only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the GST amount.

Payeezy Gateway supports Level II processing for Visa, MasterCard and American Express, and Level III processing for Visa and MasterCard.

Tax2Number
  • String [20]
  • {Write} {minOccurs=”0” maxOccurs=”1”}
tax2_number (JSON format)

Registered number associated with the tax value. Used for reference or government claims purposes and only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the GST number.

Payeezy Gateway supports Level II processing for Visa, MasterCard and American Express, and Level III processing for Visa and MasterCard.

Customer_Ref
  • String [20]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
customer_ref (JSON format)

A merchant defined value that can be used to internally identify the transaction. This value is passed through to the Payeezy Gateway unmodified, and may be searched in First Data Payeezy Gateway Real-time Payment Manager (RPM). It is passed on to the financial institution. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).

Required Character Format is ASCII.

Reference_3
  • Char [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
reference_3 (JSON format)

A merchant defined value that can be used to internally identify the transaction. This value is passed through to the Payeezy Gateway unmodified. It is not searchable and is not passed on to the financial institution. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes). Also used to pass on the Foreign Access Code for ValueLink transactions.

Required Character Format is ASCII.

Language
  • Integer
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
language (JSON format)
Selects the language the CTR is to appear in. Supported Values:
  • EN {Default}
  • FR
  • ES
Client_IP
  • String [15]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
client_ip (JSON format)
This is the IP address of the customer (i.e. client browser) connecting to the merchant. This value is stored for fraud investigation. It is not passed on to the financial institution.
Client_Email
  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
client_email (JSON format)
This is the email address of the customer connecting to the merchant. This value is stored for fraud investigation. It is not passed on to the financial institution.
user_name
  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

user_name (JSON format)

This is the user_name of the user processing the transaction. This field is visible in the Real Time Payment manager as the "User ID" and defaults to "API-(ExactID)."

Currency

  • String [3]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
currency_code (JSON format)
A currency code used for charging the transaction. Currencies and their values can be found here.

PartialRedemption

  • Boolean
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
partial_redemption (JSON format)

Submit true to allow partial redemptions, false otherwise. A partial redemption will be returned if only a portion of the requested funds are available. For example, if a transaction is submitted for $100, but only $80 is available on the customer's card, the $80 will be authorized or captured when this property is set to true. This property can be used for all types of pre-authorization and purchase transactions.

CAVV

  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
cavv (JSON format)
3-D Secure/Verified by Visa value returned by Cardinal Commerce

XID

  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
xid (JSON format)
3-D Secure/Verified by Visa value returned by Cardinal Commerce

Ecommerce_Flag

  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
ecommerce_flag (JSON format)
The value passed in this flag can be used to classify the type of payment being performed. Possible values are outlined here.

TransarmorToken

  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

transarmor_token (JSON format)

Used to submit a Transarmor token for transaction processing rather than using a credit card number for processing. If using this property, CardType must also be populated.

Note that when a terminal is set up with TransArmor, a value will be returned in this property each time a transaction is submitted using a regular card number.

This property can only be used with the v9 or higher endpoint of the API.

CardType

  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

credit_card_type (JSON format)

CardType value associated with a TransArrmor token, PayPal transaction, or if submitting a ValueLink transaction, this property's value is required to be "Gift." Required for TransArmor transactions, PayPal transactions, and ValueLink transactions that submit a card number.

Note that when a terminal is set up with TransArmor, a value will be returned in this property each time a transaction is submitted using a regular card number.

Possible values include "American Express", "Visa", "Mastercard", "Discover", "Diners Club", "JCB", "Gift", "PayPal", "Debit"

This property can only be used with the v9 or higher endpoint of the API.

EAN
  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
ean (JSON format)
ValueLink card verification value similar to CVV2 numbers on the back of credit cards. This can only be used for ValueLink transactions and is only available in the v9 or higher endpoint.

VirtualCard

  • Boolean
  • {Read/Write} {minOccurs="0" maxOccurs="1"
virtual_card (JSON format)
Flag used to indicate whether a ValueLink card is virtual or not. This can only be used for ValueLink transactions and is only available in the v9 or higher endpoint.

CardCost

  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
card_cost (JSON format)
Used for ValueLink activation transactions. This can only be used for ValueLink transactions and is only available in the v9 or higher endpoint.

FraudSuspected

  • String [var]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
fraud_suspected (JSON format)
This property can only be used with the refund or void transaction types, and is only applicable to MasterCard transactions using the v12 or higher endpoints. When fraud is suspected for a MasterCard transaction, this property should be populated with a value of "200" when issuing the refund.

CheckNumber

  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
check_number (JSON format)

The check number being used to complete payment.

This property is only applicable to the v13 or higher endpoint.

CheckType

  • String [1]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
check_type (JSON format)

Allowed values for this field are "P" (personal check), or "C" (corporate check).

This property is only applicable to the v13 or higher endpoint.

BankAccountNumber

  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
account_number (JSON format)

The bank account number of the check being used to complete payment.

This property is only applicable to the v13 or higher endpoint.

BankRoutingNumber

  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
bank_id (JSON format)

The bank routing number of the check being used to complete payment.

This property is only applicable to the v13 or higher endpoint.

CustomerName

  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
cardholder_name (JSON format)

The name of the customer making the payment.

This property is only applicable to the v13 or higher endpoint.

CustomerIDType

  • Integer [1]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
customer_id_type (JSON format)

The type of ID used to validate the identity of the check holder. Allowed values are:

  • Driver's license: 0
  • Social Security Number: 1
  • Tax ID: 2
  • Military ID: 3
This property is only applicable to the v13 or higher endpoint.

CustomerID

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
customer_id_number (JSON format)

Number on the type of identification specified in the previous property.

This property is only applicable to the v13 or higher endpoint.

TPPID

  • String [6]
  • {Read/Write}{minOccurs="0" maxOccurs="1"}

tpp_id (JSON format)

Third-Party Property ID, also known as Partner ID.

If you are a Third-Party Processor, this can be used to include your ID when processing.

This property is only applicable to the v14 endpoint.

SplitTenderID

  • String
  • {Read/Write}{minOccurs="0" maxOccurs="1"}

split_tender_id (JSON format)

Split Tender ID.

A partially-authorized transaction will generate a Split Tender ID. Subsequent transactions to complete the authorization should include the Split Tender ID so that all the transactions comprising that authorization can be linked.

This property is only applicable to the v13 or higher endpoint.

SplitShipmentNumber

  • String
  • {Read/Write}{minOccurs="0" maxOccurs="1"}

split_shipment_number(JSON format)

 

SplitShipmentNumber

String ("xx/yy")

where: xx = number of the shipment
where: yy = total shipments

Example: Shipment 2 of 5 => Split_Shipment = "02/05"

<SplitShipmentNumber>02/05</SplitShipmentNumber>

This property is only applicable to the v15 or higher endpoint.

 

Note: Split Shipment feature is required whenever the same authorization code is being used for multiple transactions entries. The total number of shipments must be greater than 1; if the amount sent is 01/01 as a value for the split_shipment_number, Compass will reject the transaction with a 225 response code.

Additionally, Split Shipment through the Omaha back-end is not supported. 

4.1 Address Properties

From the V14 endpoint onwards, the VerificationStr1 property has been replaced with the new compound Address element to allow greater flexibility in the specification of address information. It can be used to send AVS address information with credit transactions, or check address information with TeleCheck transactions.

Element lengths are softly enforced; that is, elements longer than the specified maximum are truncated to the maximum length before processing. This truncation may affect AVS validation, or any address-based Fraud Filters, so please ensure you

Property Length Format Required/Optional Description

Address

address (JSON format)

      Parent of the properties listed below.

Address1

address1 (JSON format)

30 String Optional  

Address2

address2 (JSON format)

28 String Optional  

City

city (JSON format)

20 String Optional  

State

state (JSON format)

2 String Optional  

Zip

zip (JSON format)

10 String Optional  

CountryCode

country_code (JSON format)

2 String Optional  

PhoneNumber

phone_number (JSON format)

14 String Optional Non digits will be removed before processing

PhoneType

phone_type (JSON format)

1 String Optional

Only the following values are accepted:

H = Home

W = Work

D = Day

N = Night

PhoneType is required when the PhoneNumber field is populated in a transaction request. Otherwise, it is optional.

 

The following is an example of a credit transaction including the Address element, using the REST format:

<?xml version="1.0" encoding="utf-8" ?>
<Transaction>
  <ExactID>A1234-01</ExactID>
  <Password>12345pwd</Password>
  <Card_Number>5454545454545454</Card_Number>
  <CardHoldersName>ARTHUR DIGBY SELLERS</CardHoldersName>
  <Transaction_Type>00</Transaction_Type>
  <Expiry_Date>0915</Expiry_Date>
  <DollarAmount>168.67</DollarAmount>
  <Address>
    <Address1>21 Jump Street</Address1>
    <City>Los Angeles</City>
    <Zip>90210</Zip>
    <PhoneNumber>5557891234</PhoneNumber>
    <PhoneType>W</PhoneType>
  </Address>
</Transaction>

 

The same example, this time in JSON format:

{
  "gateway_id": "A1234-01", 
  "password": "12345pwd", 
  "cardholder_name": "ARTHUR DIGBY SELLERS", 
  "cc_number": "5454545454545454", 
  "cc_expiry": "0915",
  "transaction_type": "00",
  "amount": 168.67,
  "address" : {
    "address1": "21 Jump Street",
    "city": "Los Angeles",
    "zip": "90210",
    "phone_number": "5557891234",
    "phone_type": "W"
  }
}

 

4.2 Level 2 Properties

 

Tax1Amount

  • Double [99,999.99]
  • {Write} {minOccurs=”0” maxOccurs=”1”}

tax1_amount (JSON format)

Tax value included in total amount, only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the PST amount.

Payeezy Gateway only supports Level II processing for Visa and MasterCard. It does not support American Express Level II processing.

Tax1Number

  • String [20]
  • {Write} {minOccurs=”0” maxOccurs=”1”}

tax1_number (JSON format)

Registered number associated with the tax value. Used for reference or government claims purposes and only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the PST number.

Payeezy Gateway only supports Level II processing for Visa and MasterCard. It does not support American Express Level II processing.

Tax2Amount

  • Double [99,999.99]
  • {Write} {minOccurs=”0” maxOccurs=”1”}

tax2_amount (JSON format)

Tax value included in total amount, only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the GST amount.

Payeezy Gateway only supports Level II processing for Visa and MasterCard. It does not support American Express Level II processing.

Tax2Number

  • String [20]
  • {Write} {minOccurs=”0” maxOccurs=”1”}

tax2_number (JSON format)

Registered number associated with the tax value. Used for reference or government claims purposes and only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the GST number.

Payeezy Gateway only supports Level II processing for Visa and MasterCard. It does not support American Express Level II processing.

Customer_Ref

  • String [20]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

customer_ref (JSON format)

A merchant defined value that can be used to internally identify the transaction. This value is passed through to the Payeezy Gateway unmodified, and may be searched in First Data Payeezy Gateway Real-time Payment Manager (RPM). It is passed on to the financial institution. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).

Required Character Format is ASCII.

 

4.3 Level 3 Properties

The following properties are used to populate additional information about the transaction, including shipping details and line item

information. These properties are available for the v9 or higher endpoint of the API only.

NOTE: Although some of the properties are optional, refer to the table below to determine which fields must be populated to qualify for best Level 3 interchange rate.

Payeezy Gateway only supports Level III processing for Visa and MasterCard. It does not support American Express Level III processing.

For the following table, Format abbreviations are:

  • A - Alphanumeric
  • N - Numeric (0-9) allowing decimal (.)
  • B - Boolean (0,1)

All alpha characters should be in capital letters unless otherwise specified.

Property

Length

Format

Required/ Optional

Description

Level3

level3 (JSON format)

   

Required

Parent of the properties listed below.

TaxAmount

  • {Write} {minOccurs=”0” maxOccurs=”1”}

tax_amount (JSON format)

12

N

Required

Tax amount in dollars and cents. Child property of Level 3.

2 decimal/right justified/zero filled or space filled, (20.00)

Value should be >= $0.00

TaxRate

  • {Write} {minOccurs=”0” maxOccurs=”1”}

tax_rate (JSON format)

4

N

Optional

Tax rate applied to the item

2 decimal/right justified/zero filled or space filled, (1.00 = 1%)

AltTaxAmount

  • {Write} {minOccurs=”0” maxOccurs=”1”}

alt_tax_amount (JSON format)

9

N

Optional

Total amount of alternate tax associated with this transaction.

Note: If AltTaxAmount is populated, "AltTaxID” is required

 

AltTaxId

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

alt_tax_id (JSON format)

14

A

Optional

Tax ID number for the alternate tax associated with this transaction.

DiscountAmount

  • {Write} {minOccurs=”1” maxOccurs=”1”}

discount_amount (JSON format)

12

N

Required

Amount of discount applied to the total transaction.

2 decimal/right justified/zero filled or space filled, (20.00)

DutyAmount

  • {Write} {minOccurs=”0” maxOccurs=”1”}

duty_amount (JSON format)

12

N

Required

Total charges for any import and/or export duties included in this transaction.

2 decimal/right justified/zero filled or space filled, (20.00)

FreightAmount

  • {Write} {minOccurs=”0” maxOccurs=”1”}

freight_amount (JSON format)

12

N

Required

Total freight or shipping and handling charges.

2 decimal/right justified/zero filled or space filled, (20.00)

ShipFromZip

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

ship_from_zip (JSON format)

10

A

Optional

 

The zip/postal code of the location from which the goods were shipped.

ShipToAddress

ship_to_address (JSON format)

   

Optional

Parent of the properties listed below.

Address1

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

address_1 (JSON format)

28

A

Optional

The Street Address of the “ship to” location.

Required Character Format is UPPER.

City

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

city (JSON format)

20

A

Optional

The City of the “ship to” location.

Required Character Format is UPPER.

State

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

state (JSON format)

2

A

Optional

The State of the “ship to” location.

Required Character Format is UPPER.

Zip

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

zip (JSON format)

2

A

Optional

The Zip/postal code of the “ship to” location.

Country

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

country (JSON format)

2

A

Optional

The ISO-assigned code of the country to which the goods were shipped.

US – United States,CA – Canada,GB – Great Britain,UK – United Kingdom,“ “ – Blank for all other countries)

CustomerNumber

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

customer_number (JSON format)

20

A

Optional

Purchase order or other number used by merchant’s customer to track the order.

Email

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

email (JSON format)

50

A

Optional

The Accountholder’s email address associated with the transaction.

Name

  • String [28]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

name (JSON format)

28

A

Optional

The Accountholder’s name associated with the transaction.

asterisk should precede last name ex: *LAST

Phone

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

phone (JSON format)

14

A

Optional

The Accountholder’s phone number associated with the transaction.

AAAEEENNNNXXXX where: AAA = Area Code, EEE = Exchange, NNNN = Number, XXXX = Extension

LineItem

line_items (JSON format)

   

Required

Parent of the properties listed below. There is a limit of 99 line items for a single transaction.

CommodityCode

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

commodity_code (JSON format)

12

N

Required

The commodity code used to classify the item purchased. For a complete list of Commodity Codes click here.

 

Description

  • {Read/Write} {minOccurs=”1” maxOccurs=”1”}

description (JSON format)

26

N

Required

Item description.

Required Character Format is ASCII.

 

DiscountAmount

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

discount_amount (JSON format)

12

N

Required

The discounted amount for the line item.

2 decimal/right justified/zero filled or space filled, (100.00)

 

DiscountIndicator

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

discount_indicator (JSON format)

 

B

Required

Indicator for whether a discount is present on the item or not.

1 – Discounted

0 – Not Discounted

 

GrossNetIndicator

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

gross_net_indicator (JSON format)

 

B

Required

Indicates whether tax is included in the total amount or not.

1 – Tax included

0 – Tax Excluded

 

LineItemTotal

  • {Read/Write} {minOccurs=”1” maxOccurs=”1”}

line_item_total (JSON format)

12

N

Required

The amount of the item. Normally calculated as price multiplied by quantity.

2 decimal/right justified/zero filled, (200.00)

 

ProductCode

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

product_code (JSON format)

12

A

Required

The UPC product code for the line item.

Required Character Format is ASCII.

 

Quantity

  • {Read/Write} {minOccurs=”1” maxOccurs=”1”}

quantity (JSON format)

5

N

Required

 

Number of units of the item purchased

 

 

TaxAmount

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

tax_amount (JSON format)

12

N

Optional

The amount of tax charged on the line item.

2 decimal/right justified/zero filled or space filled (50.00)

 

TaxRate

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

tax_rate (JSON format)

4

N

Optional

The rate of tax charged on the line item.

2 decimal/right justified/zero filled or space filled, (1.00 = 1%)

TaxType

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

tax_type (JSON format)

4

A

Optional

Type of tax being applied.

UnitCost

  • {Read/Write} {minOccurs=”1” maxOccurs=”1”}

unit_cost (JSON format)

12

N

Required

The per unit cost of the line item.

4 decimal/right justified/zero filled or space filled, (100.0000)

UnitOfMeasure

  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

unit_of_measure (JSON format)

12

A

Required

The unit of measure, or unit of measure code used for this item

Note: In order to process Level II and/or Level III data, it must be enabled on your merchant account. Please contact your First Data Sales Representative for more details. Please note that Level III data is not supported for American Express card types.

 

The following is an example of a transaction that makes use of the Level 3 fields, using the REST format.

<?xml version="1.0" encoding="utf-8" ?>
<Transaction>
  <ExactID>A1234-01</ExactID>
  <Password>12345pwd</Password>
  <Card_Number>5454545454545454</Card_Number>
  <CardHoldersName>ARTHUR DIGBY SELLERS</CardHoldersName>
  <Transaction_Type>00</Transaction_Type>
  <Expiry_Date>0915</Expiry_Date>
  <DollarAmount>168.67</DollarAmount>
    <Level3>
     <TaxAmount>8.84</TaxAmount>
     <TaxRate>7.25</TaxRate>
     <AltTaxAmount>0.0</AltTaxAmount>
     <AltTaxId></AltTaxId>
     <DiscountAmount>30.00</DiscountAmount>
     <DutyAmount>12.90</DutyAmount>
     <FreightAmount>24.99</FreightAmount>
     <ShipFromZip>90265</ShipFromZip>
    <ShipToAddress>
       <Address1>1234 QUINTANA RD</Address1>
       <City>VENICE</City>
       <Country>US</Country>
       <CustomerNumber>90125</CustomerNumber>
       <Email>JACKIE@JACKCUSTOMER.COM</Email>
       <Name>ARTHUR DIGBY *SELLERS</Name>
       <Phone>8185551212</Phone>
       <State>CA</State>
       <Zip>90291</Zip>
    </ShipToAddress>
    <LineItem>
        <CommodityCode>014048675309</CommodityCode>
        <Description>CARPET CLEANER</Description>
        <DiscountAmount>30.00</DiscountAmount>
        <DiscountIndicator>1</DiscountIndicator>
        <GrossNetIndicator>1</GrossNetIndicator>
        <LineItemTotal>107.20</LineItemTotal>
        <ProductCode>PN0339763321</ProductCode>
        <Quantity>PN0339763321</Quantity>
        <TaxAmount>7.25</TaxAmount>
        <TaxRate>7.25</TaxRate>
        <TaxType>4</TaxType>
        <UnitCost>2.33</UnitCost>
        <UnitOfMeasure>QTL</UnitOfMeasure>
    </LineItem>
    <LineItem>
        <CommodityCode>133042775322</CommodityCode>
        <Description>NON DAIRY CREAMER</Description>
        <DiscountAmount>00.00</DiscountAmount>
        <DiscountIndicator>0</DiscountIndicator>
        <GrossNetIndicator>1</GrossNetIndicator>
        <LineItemTotal>23.58</LineItemTotal>
        <ProductCode>PN0000090125</ProductCode>
        <Quantity>1</Quantity>
        <TaxAmount>1.59</TaxAmount>
        <TaxRate>7.25</TaxRate>
        <TaxType>4</TaxType>
        <UnitCost>00.22</UnitCost>
        <UnitOfMeasure>CS</UnitOfMeasure>
    </LineItem>
  </Level3>
</Transaction>

JSON Level 3 Example:

curl -H 'Content-Type: application/json; charset=UTF-8' \
     -H 'Accept: application/json' \
     -d '{ 
"gateway_id": "A1234-01", 
"password": "12345pwd", 
"transaction_type": "00", 
"amount": 11, 
"cardholder_name": "ARTHUR DIGBY SELLERS", 
"cc_number": "5454545454545454", 
"cc_expiry": "0315",
"level3": {
	"ship_from_zip": "90265",
	"duty_amount": 12.90,
	"discount_amount": 30.00,
	"freight_amount": 24.99,
	"line_items": [{
		"description": "CARPET CLEANER",
		"product_code": "PN0339763321",
		"quantity": 5,
		"unit_of_measure": "QTL",
		"line_item_total": 107.20,
		"commodity_code": "014048675309",
		"unit_cost": 2.33}],
	"ship_to_address": {
		"name": "ARTHUR *SELLERS",
		"address_1": "1234 QUINTANA RD",
		"city": "VENICE"}}
}' \
https://api.globalgatewaye4.firstdata.com/transaction/v11

4.4 PayPal Properties

The following PayPal properties are used to record PayPal transactions that have already been processed into the Payeezy Gateway system. To use any of the PayPal transaction types, the "CardType" property must be set to "PayPal". Note that the below properties are only applicable to PayPal Purchase, Pre-Authorization, or Order transactions. To perform a refund, pre-authorization completion, or void against a PayPal transaction, the normal tagged transaction types can be used. Alternately, these types of secondary transactions can be performed through the Realtime Payment Manager interface.

NOTE: In order to perform tagged transactions against PayPal transactions via the API, a Payment Page must be set up with the same PayPal credentials as used for the original transactions, and the API terminal used for these tagged transactions must be the same terminal used by the Payment Page for processing. Information on entering these credentials can be found here.

Property Description

PaypalTransactionDetails

paypal_transaction_details (JSON format)

Parent of the properties listed below.

PayerID

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
payer_id (JSON format)
PayerID used for a PayPal transaction

GrossAmountCurrencyID

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
gross_amount_currency_id (JSON format)
Currency ID applicable for the gross value of a PayPal transaction.

Sucess

  • Boolean
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
success (JSON format)
Success indicator of a PayPal transaction

Authorization

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
authorization (JSON format)
Authorization data returned from PayPal for a transaction

Message

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
message (JSON format)
Explanatory message returned by PayPal for a PayPal transaction

CorrelationID

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
correlation_id (JSON format)
Correlation ID of a PayPal transaction, which uniquely ties it to PayPal

Timestamp

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
timestamp (JSON format)
Applicable timestamp for a PayPal transaction

Integrating PayPal's Express Checkout API

Payeezy Gateway Web Service API enables merchants to integrate PayPal’s Express Checkout API into their processing environment. A PayPal merchant account is required.

The following high level steps are used when integrating with PayPal Express Checkout API and Payeezy Gateway payment capture interface.

  1. Customer chooses PayPal from merchant’s check out page.
  2. Customer’s browser is redirected to PayPal’s web site.
  3. Customer logs into PayPal, authenticates credentials, and approves amount to be deducted from their account.
  4. Customer is returned to merchant’s web site for order confirmation.
  5. Merchant sends Express Checkout API request to PayPal to process payment transaction.
  6. Payeezy Gateway captures the payment details to be used for future actions such as voids, refunds and reporting.

Once the PayPal transaction is completed it is logged into Payeezy Gateway just like a regular credit card transaction with the above API message and merchants can do a secondary transaction (Refund/Void) against it via Transaction Search in the Real-Time Payment Manager.

You will need to follow PayPal’s instructions for integration which can be found at this link:

https://developer.paypal.com/webapps/developer/docs/classic/products/#ec

Payeezy Gateway JSON Data Content:

{

"gateway_id":"A00123-01",

"amount":201.50,

"transaction_type":"07",

"credit_card_type":"Paypal",

"cardholder_name":" ARTHUR DIGBY SELLERS",

"password":"secret",

"paypal_transaction_details": {

"correlation_id":"11d8cac11e8",

"timestamp":" 2012/04/16 15:00:06",

"authorization":"O-123456789ABCDEFGH",

"payer_id":"ADUMMYPAYERID",

"gross_amount_currency_id":"USD",

"success":true,

"message":"Success"}

}

the credit_card_type value needs to be "paypal" (case insensitive)

 

4.5 Soft Descriptor Properties

The following properties are used to set soft descriptor information for a transaction on a case-by-case basis. These properties are only compatible with v11 and higher of the API and can only be used with the following transaction types:

  • Purchase
  • Pre-Authorization
  • Pre-Authorization-Completion
  • Void/Refund

Important Note About Using Soft Descriptors: Dynamic soft descriptors are submitted both at the authorization and the settlement of a transaction. If you would like to use Soft Descriptors, please contact your First Data Relationship Manager or Sales Rep and have them set your "Foreign Indicator" in your "North Merchant Manager File" to "5". To learn more about Dynamic Soft Descriptors, please click here.

 

Property Description
SoftDescriptor Parent of the properties listed below. Note: to use any of the properties listed below, this property must be used as their parent.

DBAName

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
dba_name (JSON format)
Business name


Required Character Format is ASCII.

Street

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
street (JSON format)

Business address

Required Character Format is ASCII.

City

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
city (JSON format)
Business city


Required Character Format is ASCII.

Region

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
region (JSON format)
Business region


Required Character Format is ASCII.

PostalCode

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
postal_code (JSON format)
Business postal/zip code

CountryCode

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
country_code (JSON format)
Business country

MID

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
mid (JSON format)
Merchant ID

MCC

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
mcc (JSON format)
Enter your Merchant Category Code

MerchantContactInfo

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
merchant_contact_info (JSON format)
Merchant contact information


Required Character Format is ASCII.

 

Soft Descriptor JSON Example

 

{ 
"gateway_id": "A00001-01", 
"password": "zzzz", 
"transaction_type": "00", 
"amount": 11, 
"cardholder_name": "JEFFREY LEBOWSKI", 
"cc_number": "4111111111111111", 
"cc_expiry": "0314", 
"soft_descriptor": {
	"dba_name": "Autobahn"}
}

 

4.6 Telecheck Properties

The following properties are only applicable for the Telecheck method of payment, and can only be used with the v13 endpoint or higher of the API.

Property Description

CheckNumber

  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
check_number (JSON format)
The check number being used to complete payment.

CheckType

  • String [1]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
check_type (JSON format)
Allowed values for this field are "P" (personal check), or "C" (corporate check).

BankAccountNumber

  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
account_number (JSON format)
The bank account number of the check being used to complete payment.

BankRoutingNumber

  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
bank_id (JSON format)
The bank routing number of the check being used to complete payment.

CustomerName

  • String [30]
  • {Read/Write} {minOccurs="1" maxOccurs="1"}
cardholder_name (JSON format)
The name of the customer making the payment.

CustomerIDType

  • Integer [1]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
customer_id_type (JSON format)

The type of ID used to validate the identity of the check holder. Allowed values are:

  • Driver's license: 0
  • Social Security Number: 1
  • Tax ID: 2
  • Military ID: 3

CustomerID

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
customer_id_number (JSON format)
Number on the type of identification specified in the previous property.

ReleaseType

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

release_type (JSON format)

Release Type, can be one of "D", "P", "S", or "X".

GiftCardAmount

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

gift_card_amount (JSON format)

Gift card amount associated with the transaction.

DateOfBirth

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

date_of_birth (JSON format)

Customer's date of birth in MMDDYYYY format.

VIP

  • Boolean
  • {Read} {minOccurs=”0” maxOccurs=”1”}

vip (JSON format)

VIP status of the transction.

RegistrationNo

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

registration_no (JSON format)

Registration number associated with the transaction.

RegistrationDate

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

registration_date (JSON format)

Registration date in MMDDYYYY format.

ClerkID

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

clerk_id (JSON format)

Clerk ID number associated with the transaction.

DeviceID

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

device_id (JSON format)

Device ID associated with the transaction.

MICR

  • String [30]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}

micr (JSON format)

MICR associated with the transaction.

 

4.7 Fees

A field indicating “Fee Over-ride” is an optional field in the Web Service API. The logic to determine Fee processing will follow the following path:

  • If the optional Fee Over-ride field is populated by the merchant, the associated Fee will be accepted by the system. This Fee will ”Over-ride” whatever is established in the Gateway for the merchant.
  • If the optional Fee field Over-ride is absent or not populated by the merchant, the Fee structure established at the Gateway will be applied to the transaction. This is considered the standard Fee model.

 

Depending upon the transaction mode selected, the Fee will be treated as:

  • Part of the Order Amount following the authorization/completion of the aggregated Order amount. This mode will support the Split Funding of fees to a separately designated DDA.

  • Separate from the Order Amount and following a separate and distinct authorization/completion path from the original Order amount.

 

Property

Description

FeeAmount

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
  • JSON: fee_amount
(V18 forward)
This is added to DollarAmount to produce the total charged. Specifying FeeAmount overrides any amount calculated for fees based on the configuration of the terminal. Ignored if fees are not enabled for terminal.

 

Note: Fees and DCC/DP are mutually exclusive (the Gateway will not allow selection of Fees if DCC and/or DP are activated).

 

4.8 DCC Properties

The v18 and higher endpoint of the API adds the powerful DCC (Dynamic Currency Conversion) service. A payment solution that allows international customers to pay in their credit card currency.

NOTE: Please contact your First Data sale representative for additional information.This section should be used in conjunction with the DCC/DP Merchant and Rate Card API article as a Merchant needs to get the RateResponseSignature from the Card Rate API. Click here to view this article now.

Merchants can include DCC fields in the transaction requests, indicating DCC-Opt-In and referencing a rate response obtained in a previous card rate request.

The terminal needs to be enabled for Dynamic Currency in the Gateway.

The DCC properties are placed inside a DynamicCurrency element (JSON, dynamic_currency). This element has the following properties:

Property

Description

OptedIn

  • String
  • {Read/Write} {minOccurs=”1” maxOccurs=”1”}
  • JSON: opted_in
(V18 forward)
"true" or "false". Whether customer has opted-in to DCC conversion

RateResponseSignature

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
  • JSON: rate_response_signature
(V18 forward)

 

The value of the "rate_response_id" from the exchange rate API (card rate request)
 
 

SOAP / XML Example:

<DynamicCurrency>
<OptedIn>true</OptedIn>
<RateResponseSignature>123-1604561b0528eb909bcc38bb146f166ec6540ab3b7b326d6e5b990ec73c030f8</RateResponseSignature>
</DynamicCurrency>

 

JSON Example:

"dynamic_currency": {
"opted_in": "true",
"rate_response_signature": "123-1604561b0528eb909bcc38bb146f166ec6540ab3b7b326d6e5b990ec73c030f8"
}

In the response, an element ForeignCurrencyDetails (JSON: foreign_currency_details) contains the foreign currency transaction details. Please see the section entitled Foreign Currency Details Properties for additional information.

Important: If the currency of the transaction request is different from the terminal's, any Dynamic Currency data will be ignored.
 

4.9 DP Properties

The v18 or higher endpoint of the API adds another service known as DP (Dynamic Pricing). DP provides merchants with the ability to offer their international cardholders the choice to view and pay for goods and services in their own currency.

NOTE: Please contact your First Data sale representative for additional information. This section should used alongside with the DCC/DP Merchant and Rate Card API article. Click here to view this article now.

Merchants can include DP fields in the transaction requests, indicating currency conversion opt-in by the customer, and referencing a rate response obtained in a previous merchant rate request.

The terminal needs to be enabled for Dynamic Pricing at the Gateway.

Important: If the currency of the transaction request is different from the terminal's, any Dynamic Pricing data will be ignored.

The DP properties are placed inside a DynamicPricing element (JSON, dynamic_pricing). This element has the following properties:

 

Property

Description

OptedIn

  • String
  • {Read/Write} {minOccurs=”1” maxOccurs=”1”}
  • JSON: opted_in
(V18 forward)
"true" or "false". Whether customer has opted-in to currency conversion

RateResponseSignature

  • String
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
  • JSON: rate_response_signature
(V18 forward)
The value of the "rate_response_id" from the exchange rate API (merchant rate request)

 

SOAP / XML Example:

<DynamicCurrency>
<OptedIn>true</OptedIn>
<RateResponseSignature>123-1604561b0528eb909bcc38bb146f166ec6540ab3b7b326d6e5b990ec73c030f8</RateResponseSignature>
</DynamicCurrency>

 

JSON Example:

"dynamic_currency": {
"opted_in": "true",
"rate_response_signature": "123-1604561b0528eb909bcc38bb146f166ec6540ab3b7b326d6e5b990ec73c030f8"
}

Note: In the response, an element ForeignCurrencyDetails (JSON: foreign_currency_details) contains the foreign currency transaction details. Please see Foreign Currency Details Properties section for more information.

 

4.10 Foreign Currency Details Properties

The v18 or higher endpoint of the API supports the Foreign Currency Details. The following properties apply:

Property

Description

DCCIndicator

  • String
  • {minOccurs=”1” maxOccurs=”1”}
  • JSON: dcc_indicator
(V18 forward)
1 or 3. 1 if OptedIn in the request was true, 3 if OptedIn in the request was false.

ForeignAmount

  • String
  • {minOccurs=”0” maxOccurs=”1”}
  • JSON: foreign_amount
(V18 forward)
The foreign amount from the rate response referenced in the request, if supplied.

ForeignCurrencyCode

  • String
  • {minOccurs=”0” maxOccurs=”1”}
  • JSON: foreign_currency_code
(V18 forward)

The foreign currency code from the rate response referenced in the request, if supplied.

ExchangeRate

  • String
  • {minOccurs=”0” maxOccurs=”1”}
  • JSON: exchange_rate
(V18 forward)
The exchange rate from the rate response referenced in the request, if supplied.

MarginRate

  • String
  • {minOccurs=”0” maxOccurs=”1”}
  • JSON: margin_rate
(V18 forward)
The margin rate from the rate response referenced in the request, if supplied.

RateSource

  • String
  • {minOccurs=”0” maxOccurs=”1”}
  • JSON: rate_source
(V18 forward)
The rate source from the rate response referenced in the request, if supplied.

 

When refunding or voiding tagged transactions, or completing a Pre-authorization with DCC indicator = 1, the DynamicCurrency / dynamic_currency need not be supplied, the exchange rate for the transaction will be automatically looked up and applied. This will be reflected in following element in the response: ForeignCurrencDetails / foreign_currency_details.

Transactions that require the DynamicCurrency element to be processed as a DCC transaction:

Transaction Type
Code
Purchase 00
Pre Authorization 01

Exchange rates will be automatically looked up if the original / referenced transaction had a DCC indicator of 1:

Transaction Type

Code

Pre Auth Complete

02

Refund

04

Tagged Purchase

30

Tagged Pre auth

31

Tagged Completion

32

Tagged Void

33

Tagged Refund

34

For Partial Authorizations (where PartialRedemption is set to "Y") the foreign amount will be re-calculated as the partial amount multiplied by the exchange rate.

 

5 Response Properties

The following properties are returned in the response. In addition, all the Request Properties are also returned. The Request Properties returned in the Response are populated with the values actually used to process the transaction. Any changes made to a Request Property while processing will be reflected by the altered return value. In addition, the Request Properties Transaction_Tag and Authorization_Num are overridden by new return values. The new values reference the new transaction that has been processed. Note that the minOccurs and maxOccurs values here apply to v9 or higher of the API only; for v8 they are all considered required fields to ensure backwards-compatibility.

Property Description
LogonMessage
  • String [255]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
(V8 only)
Returned by Global Gateway e4℠ upon successful Authentication. Indicates the location and version of the server that provided authentication.
Transaction_Error
  • Boolean
  • {Read} {minOccurs=”1” maxOccurs=”1”}
transaction_error (JSON format)
This property indicates that there was an error during the processing of the transaction. Please refer to eCommerce Response Codes (ETG Codes) for further information.
Transaction_Approved
  • Boolean
  • {Read} {minOccurs=”1” maxOccurs=”1”}
transaction_approved (JSON format)
This property indicates that the bank approved a transaction and there are no pending errors. If further information is required, please check the Optional Response properties.
Exact_Resp_code
  • String [2]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
exact_resp_code (JSON format)
This property indicates the processing status of the transaction. Please refer to the section on Exception Handling for further information. The Transaction_Error property will return True if this property is not “00”.
Exact_Message
  • String [50]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
exact_message (JSON format)
Message that accompanies the Exact_Resp_code.
Bank_Resp_code
  • String [3]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
This is a 2 or 3 digit code, provided by the financial institution, indicating the approval status of a transaction. The meaning of these codes is defined by the various financial institutions and is not under the control of the Global Gateway e4℠ web service API or Gateway. Please refer to the Transaction_Approved property for the approval status of a transaction.
Bank_Message
  • String [80]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
A message provided by the financial institution describing the Response code above.
Bank_Resp_code_2
  • String [2]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
A secondary response provided returned by the financial institution.
Transaction_Tag
  • Integer
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
A unique identifier to associate with a tagged transaction. This value overrides any value sent for the Request Property of the same name.
Authorization_Num
  • String [8]
  • {Read/Write} {minOccurs=”0” maxOccurs=”1”}
This is the authorization number returned by the cardholder’s financial institution when a transaction has been approved. This value overrides any value sent for the Request Property of the same name.
SequenceNo
  • String [50]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
A digit sequentially incremented number generated by Global Gateway e4℠ and passed through to the financial institution. It is also passed back to the client in the transaction response. This number can be used for tracking and audit purposes.
AVS
  • String [1]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Supported AVS Results:
  • X = exact match, 9 digit zip
  • Y = exact match, 5 digit zip
  • A = address match only
  • W = 9 digit zip match only
  • Z = 5 digit zip match only
  • N = no address or zip match
  • U = address unavailable
  • G = non-North American issuer, does not participate
  • R = issuer system unavailable
  • E = not a Mail\Phone order
  • S = service not supported
  • Q = Bill to address did not pass edit checks
  • D = International street address and postal code match
  • B = International street address match, postal code not verified due to incompatable formats
  • C = International street address and postal code not verified due to incompatable formats
  • P = International postal code match, street address not verified due to incompatable format
  • 1 = Cardholder name matches
  • 2 = Cardholder name, billing address, and postal code match
  • 3 = Cardholder name and billing postal code match
  • 4 = Cardholder name and billing address match
  • 5 = Cardholder name incorrect, billing address and postal code match
  • 6 = Cardholder name incorrect, billing postal code matches
  • 7 = Cardholder name incorrect, billing address matches
  • 8 = Cardholder name, billing address, and postal code are all incorrect
CVV2
  • String [1]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
The CVV2 authentication code returned from the bank. Note: the value is null if CVV2 is not supported.
Supported CVV Results:
  • M = CVV2 / CVC2/CVD Match.
  • N = CVV2 / CVC2/CVD No Match.
  • P = Not Processed.
  • S = Merchant has indicated that CVV2 / CVC2/CVD is not present on the card.
  • U = Issuer is not certified and / or has not provided Visa encryption keys.
Retrieval_Ref_No
  • String [13]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
The reference number returned with an AVS Result.
MerchantName
  • String [50]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by Global Gateway e4℠ upon successful Authentication.
MerchantAddress
  • String [50]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by Global Gateway e4℠ upon successful Authentication.
MerchantCity
  • String [25]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by Global Gateway e4℠ upon successful Authentication.
MerchantProvince
  • String [2]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by Global Gateway e4℠ upon successful Authentication.
MerchantCountry
  • String [50]
  • {Read
Returned by Global Gateway e4℠ upon successful Authentication.
MerchantPostal
  • String [12]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by Global Gateway e4℠ upon successful Authentication.
MerchantURL
  • String [25]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Returned by Global Gateway e4℠ upon successful Authentication.
CTR
  • String [var]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Displays the bank required Customer Transaction Record. This information must be displayed to the customer upon completion of all transactions, Approved or Declined.
CurrentBalance
  • String [var]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Current balance of a ValueLink card. This is only used for ValueLink transactions and is only available in the v9 or higher endpoint.
PreviousBalance
  • String [var]
  • {Read} {minOccurs=”0” maxOccurs=”1”}
Previous balance of a ValueLink card. This is only used for ValueLink transactions and is only available in the v9 or higher endpoint.

AmexFraud

  • String
  • {Read}{minOccurs="0" maxOccurs="1"}

Support (AF) Amex Fraud Mitigation Reply Format Indicators

Indicator Response Fields: 5digit code one digit each in the order of; Zip Code, Street, Name, Telephone, Email

Indicator Codes:

Y = Match
N = No Match
S = Service Unavailable
U = Unchecked
R = Retry
<space> = Data Not Sent

When a merchant is sending in an Amex message, these fields will be returned if they were supplied in the message fields and Address Verification/Validation was requested.

This record will be returned (when supplied by Amex) if a merchant certified/recertified for First Data Compass platform after September 2010 to receive Amex Enhanced Fraud Responses

This property is only applicable to the v16 or higher endpoint.

ForeignCurrencyDetails

This is only used for DCC/DP service transaction and only available in the v18 or higher endpoint.

   

 

6 SOAP Message Format

The SOAP style Payeezy Gateway Web Service API uses an RPC/Encoded message as defined in the SOAP 1.1 protocol

The RPC/Encoded standard does allow for some variation to occur within the formatting of a SOAP message. This can occur with both the Request and Response, and the Payeezy Gateway Web Service API handles these variations in a predictable way. The following sections on Request Message Format and Response Message Format describes some of the variations that can occur with the SOAP message.

The World Wide Web Consortium defines the standard for the RPC/Encoded protocol. Documentation on it can be found athttp://www.w3.org/TR/2000/NOTE-SOAP-20000508.

6.1 Request Message Format

The Payeezy Gateway Web Service API is able to handle certain variations in the SOAP message format for the Request. The greatest variation supported is in how the Transactions struct is defined in the Request message.

Referencing or embedding may be used to define the Transaction struct element. The Transaction struct can be defined by referencing it within the Process element. Example 5.1 provides an example of a Request message that uses a referenced Transaction struct. This example is also online at:

http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e...

The Transaction struct can also be defined by embedding it within the Process element. Example 5.2 provides an example of a Request message that uses an embedded Transaction struct.

If correctly formatted, referencing or embedding the Transaction struct element will result in the same Response being returned. The response returned is described in the section Response Message Format.

NOTE: The placeholders "string" and "boolean" in the examples would need to be replaced with actual values.

Example 5.1 SOAP Request Message with a Referenced Transaction Struct

POST /vplug-in/transaction/rpc-enc/service.asmx HTTP/1.1
Host: api.globalgatewaye4.firstdata.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e...

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/"
xmlns:types="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e..."
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:SendAndCommit xmlns:q1="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e...">
<SendAndCommitSource href="#id1" />
</q1:SendAndCommit>
<types:Transaction id="id1" xsi:type="types:Transaction">
<ExactID xsi:type="xsd:string">string</ExactID>
<Password xsi:type="xsd:string">string</Password>
<Transaction_Type xsi:type="xsd:string">string</Transaction_Type>
<DollarAmount xsi:type="xsd:string">string</DollarAmount>
<SurchargeAmount xsi:type="xsd:string">string</SurchargeAmount>
<Card_Number xsi:type="xsd:string">string</Card_Number>
<Transaction_Tag xsi:type="xsd:string">string</Transaction_Tag>
<Track1 xsi:type="xsd:string">string</Track1>
<Track2 xsi:type="xsd:string">string</Track2>
<PAN xsi:type="xsd:string">string</PAN>
<Authorization_Num xsi:type="xsd:string">string</Authorization_Num>
<Expiry_Date xsi:type="xsd:string">string</Expiry_Date>
<CardHoldersName xsi:type="xsd:string">string</CardHoldersName>
<Address xsi:type="xsd:string">string</Address>
<CVDCode xsi:type="xsd:string">string</CVDCode>
<CVD_Presence_Ind xsi:type="xsd:string">string</CVD_Presence_Ind>
<ZipCode xsi:type="xsd:string">string</ZipCode>
<Tax1Amount xsi:type="xsd:string">string</Tax1Amount>
<Tax1Number xsi:type="xsd:string">string</Tax1Number>
<Tax2Amount xsi:type="xsd:string">string</Tax2Amount>
<Tax2Number xsi:type="xsd:string">string</Tax2Number>
<Ecommerce_Flag xsi:type="xsd:string">string</Ecommerce_Flag>
<XID xsi:type="xsd:string">string</XID>
<CAVV xsi:type="xsd:string">string</CAVV>
<CAVV_Algorithm xsi:type="xsd:string">string</CAVV_Algorithm>
<Reference_No xsi:type="xsd:string">string</Reference_No>
<Customer_Ref xsi:type="xsd:string">string</Customer_Ref>
<Reference_3 xsi:type="xsd:string">string</Reference_3>
<Language xsi:type="xsd:string">string</Language>
<Client_IP xsi:type="xsd:string">string</Client_IP>
<Client_Email xsi:type="xsd:string">string</Client_Email>
</types:Transaction>
</soap:Body>
</soap:Envelope>

Example 5.2 SOAP Request Message with an Embedded Transaction Struct

POST /vplug-in/transaction/rpc-enc/service.asmx HTTP/1.1
Host: api.globalgatewaye4.firstdata.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e...

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/"
xmlns:types="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e..."
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:SendAndCommit xmlns:q1="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e..."
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<types:Transaction id="id1" xsi:type="types:Transaction">
<ExactID xsi:type="xsd:string">string</ExactID>
<Password xsi:type="xsd:string">string</Password>
<Transaction_Type xsi:type="xsd:string">string</Transaction_Type>
<DollarAmount xsi:type="xsd:string">string</DollarAmount>
<SurchargeAmount xsi:type="xsd:string">string</SurchargeAmount>
<Card_Number xsi:type="xsd:string">string</Card_Number>
<Transaction_Tag xsi:type="xsd:string">string</Transaction_Tag>
<Track1 xsi:type="xsd:string">string</Track1>
<Track2 xsi:type="xsd:string">string</Track2>
<PAN xsi:type="xsd:string">string</PAN>
<Authorization_Num xsi:type="xsd:string">string</Authorization_Num>
<Expiry_Date xsi:type="xsd:string">string</Expiry_Date>
<CardHoldersName xsi:type="xsd:string">string</CardHoldersName>
<Address xsi:type="xsd:string">string</Address>
<CVDCode xsi:type="xsd:string">string</CVDCode>
<CVD_Presence_Ind xsi:type="xsd:string">string</CVD_Presence_Ind>
<ZipCode xsi:type="xsd:string">string</ZipCode>
<Tax1Amount xsi:type="xsd:string">string</Tax1Amount>
<Tax1Number xsi:type="xsd:string">string</Tax1Number>
<Tax2Amount xsi:type="xsd:string">string</Tax2Amount>
<Tax2Number xsi:type="xsd:string">string</Tax2Number>
<Ecommerce_Flag xsi:type="xsd:string">string</Ecommerce_Flag>
<XID xsi:type="xsd:string">string</XID>
<CAVV xsi:type="xsd:string">string</CAVV>
<CAVV_Algorithm xsi:type="xsd:string">string</CAVV_Algorithm>
<Reference_No xsi:type="xsd:string">string</Reference_No>
<Customer_Ref xsi:type="xsd:string">string</Customer_Ref>
<Reference_3 xsi:type="xsd:string">string</Reference_3>
<Language xsi:type="xsd:string">string</Language>
<Client_IP xsi:type="xsd:string">string</Client_IP>
<Client_Email xsi:type="xsd:string">string</Client_Email>
</types:Transaction>
</q1:SendAndCommit>
</soap:Body>
</soap:Envelope>

6.2 Response Message Format

The Request message format allowed the Transaction struct to either be referenced or embedded. The TransactionResult struct returned in the Response message is always defined by reference. Example 5.3 provides an example of a Response message that would be returned for both Example’s 5.1 and 5.2.

NOTE: The placeholders "string" and "boolean" in the examples would need to be replaced with actual values.

Example 5.3 SOAP Response Message with a Referenced TransactionResult Struct

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/"
xmlns:types="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e..."
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q3:SendAndCommitResponse xmlns:q3="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e...">
<SendAndCommitResult href="#id1" />
</q3:SendAndCommitResponse>
<types:TransactionResult id="id1" xsi:type="types:TransactionResult">
<ExactID xsi:type="xsd:string">string</ExactID>
<Password xsi:type="xsd:string">string</Password>
<Transaction_Type xsi:type="xsd:string">string</Transaction_Type>
<DollarAmount xsi:type="xsd:string">string</DollarAmount>
<SurchargeAmount xsi:type="xsd:string">string</SurchargeAmount>
<Card_Number xsi:type="xsd:string">string</Card_Number>
<Transaction_Tag xsi:type="xsd:string">string</Transaction_Tag>
<Track1 xsi:type="xsd:string">string</Track1>
<Track2 xsi:type="xsd:string">string</Track2>
<PAN xsi:type="xsd:string">string</PAN>
<Authorization_Num xsi:type="xsd:string">string</Authorization_Num>
<Expiry_Date xsi:type="xsd:string">string</Expiry_Date>
<CardHoldersName xsi:type="xsd:string">string</CardHoldersName>
<Address xsi:type="xsd:string">string</Address>
<CVDCode xsi:type="xsd:string">string</CVDCode>
<CVD_Presence_Ind xsi:type="xsd:string">string</CVD_Presence_Ind>
<ZipCode xsi:type="xsd:string">string</ZipCode>
<Tax1Amount xsi:type="xsd:string">string</Tax1Amount>
<Tax1Number xsi:type="xsd:string">string</Tax1Number>
<Tax2Amount xsi:type="xsd:string">string</Tax2Amount>
<Tax2Number xsi:type="xsd:string">string</Tax2Number>
<Ecommerce_Flag xsi:type="xsd:string">string</Ecommerce_Flag>
<XID xsi:type="xsd:string">string</XID>
<CAVV xsi:type="xsd:string">string</CAVV>
<CAVV_Algorithm xsi:type="xsd:string">string</CAVV_Algorithm>
<Reference_No xsi:type="xsd:string">string</Reference_No>
<Customer_Ref xsi:type="xsd:string">string</Customer_Ref>
<Reference_3 xsi:type="xsd:string">string</Reference_3>
<Language xsi:type="xsd:string">string</Language>
<Client_IP xsi:type="xsd:string">string</Client_IP>
<Client_Email xsi:type="xsd:string">string</Client_Email>
<LogonMessage xsi:type="xsd:string">string</LogonMessage>
<Error_Number xsi:type="xsd:string">string</Error_Number>
<Error_Description xsi:type="xsd:string">string</Error_Description>
<Transaction_Error xsi:type="xsd:boolean">boolean</Transaction_Error>
<Transaction_Approved xsi:type="xsd:boolean">boolean</Transaction_Approved>
<EXact_Resp_Code xsi:type="xsd:string">string</EXact_Resp_Code>
<EXact_Message xsi:type="xsd:string">string</EXact_Message>
<Bank_Resp_Code xsi:type="xsd:string">string</Bank_Resp_Code>
<Bank_Message xsi:type="xsd:string">string</Bank_Message>
<Bank_Resp_Code_2 xsi:type="xsd:string">string</Bank_Resp_Code_2>
<SequenceNo xsi:type="xsd:string">string</SequenceNo>
<AVS xsi:type="xsd:string">string</AVS>
<CVV2 xsi:type="xsd:string">string</CVV2>
<Retrieval_Ref_No xsi:type="xsd:string">string</Retrieval_Ref_No>
<CAVV_Response xsi:type="xsd:string">string</CAVV_Response>
<MerchantName xsi:type="xsd:string">string</MerchantName>
<MerchantAddress xsi:type="xsd:string">string</MerchantAddress>
<MerchantCity xsi:type="xsd:string">string</MerchantCity>
<MerchantProvince xsi:type="xsd:string">string</MerchantProvince>
<MerchantCountry xsi:type="xsd:string">string</MerchantCountry>
<MerchantPostal xsi:type="xsd:string">string</MerchantPostal>
<MerchantURL xsi:type="xsd:string">string</MerchantURL>
<CTR xsi:type="xsd:string">string</CTR>
</types:TransactionResult>
</soap:Body>
</soap:Envelope>

Certain variations can occur in the SOAP message format for the Response. Variations in the message may occur in three general ways. The variations may occur if a SOAP exception is thrown, in the way the child elements are ordered in the TransactionResult struct and in the addition of new elements to the TransactionResult struct.

The first way in which the Response message may vary is if a SOAP exception is returned. This type of response is returned to indicate an error. The SOAP exception message format is completely different from a normal Response. The conditions under which a SOAP exception may occur and the format of the message sent are described in the Exception Handling section.

The second way in which the Response message may vary is in the order of the child elements contained within the TransactionResult struct. The TransactionResult struct is a complex data type. There are no requirements in the RPC/Encoded standard for the contents of such a data type to follow a fixed sequence. Overtime and with modifications to the Payment Web Service, the order of the child elements contained within the TransactionResult struct may change.

The third way in which the Response message may vary is with the addition of new child elements contained within the TransactionResult struct. With upgrades to the Payment Web Service to allow enhanced processing capabilities, the complex data type may be expanded to support additional properties. When this occurs, new elements would be automatically added to the TransactionResult struc. The existing properties / elements would always continue to be supported.

7 A Few Examples Using cURL

The following examples submit transactions using the minimal required properties for each processing scenario.

NOTE: Exact ID and Password in the request and response have been substituted with the placeholders "ExactID" and "Password".

7.1 Example 1. Pre-Authorization

This request illustrates the following:

  • using the SOAP style Payeezy Gateway Web Service API
  • passing authentication credentials as HTTP Basic Authentication username:password values
  • pre-authorizing the given credit card, which allows for capturing funds at a later time via the Completion transaction
curl -u 'ExactID:Password' \

-H 'SOAPAction: http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/SendAndCommit' \
-H 'Content-Type: text/xml' \
-d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/" xmlns:types="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/encodedTypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:SendAndCommit xmlns:q1="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/Request">
<SendAndCommitSource href="#id1" />
</q1:SendAndCommit>
<types:Transaction id="id1" xsi:type="types:Transaction">
<Transaction_Type xsi:type="xsd:string">01</Transaction_Type>
<DollarAmount xsi:type="xsd:string">15.75</DollarAmount>
<Card_Number xsi:type="xsd:string">4111111111111111</Card_Number>
<Expiry_Date xsi:type="xsd:string">1015</Expiry_Date>
<CardHoldersName xsi:type="xsd:string">Walter Sobchak</CardHoldersName>
</types:Transaction>
</soap:Body>
</soap:Envelope>' \
https://api.globalgatewaye4.firstdata.com/transaction

The resulting request headers and response:

POST /transaction HTTP/1.1
Authorization: Basic Foo4BarBazAyOjAhcGl0ZXN0
User-Agent: curl/7.21.0 (i386-apple-darwin9.8.0) libcurl/7.21.0 OpenSSL/1.0.0a zlib/1.2.5 libidn/1.19
Host: http://api.globalgatewaye4.firstdata.com
Accept: */*
SOAPAction: http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e...
Content-Type: text/xml
Content-Length: 1057
Expect: 100-continue

HTTP/1.1 100 Continue
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Date: Wed, 18 Aug 2010 17:48:07 GMT
Server: Apache
ETag: "d358d5fd6360a736466600964195fcc6"
Cache-Control: private, max-age=0, must-revalidate
Content-Length: 4591
Status: 200
Content-Type: text/xml; charset=utf-8
Vary: Accept-Encoding

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:tns="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/" xmlns:types="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e..." xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<q1:SendAndCommitResponse xmlns:q1="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-e...">
<SendAndCommitResult href="#id1">
</SendAndCommitResult>
</q1:SendAndCommitResponse>
<types:TransactionResult id="id1" xsi:type="types:TransactionResult">
<ExactID xsi:type="xsd:string">ExactID</ExactID>
<Password xsi:nil="true"></Password>
<Transaction_Type xsi:type="xsd:string">01</Transaction_Type>
<DollarAmount xsi:type="xsd:string">15.75</DollarAmount>
<SurchargeAmount xsi:nil="true"></SurchargeAmount>
<Card_Number xsi:type="xsd:string">############1111</Card_Number>
<Transaction_Tag xsi:type="xsd:string">901975484</Transaction_Tag>
<Track1 xsi:nil="true"></Track1>
<Track2 xsi:nil="true"></Track2>
<PAN xsi:nil="true"></PAN>
<Authorization_Num xsi:type="xsd:string">ET4653</Authorization_Num>
<Expiry_Date xsi:type="xsd:string">1015</Expiry_Date>
<CardHoldersName xsi:type="xsd:string">Donald Kerabatsos</CardHoldersName>
<Address xsi:nil="true"></Address>
<CVDCode xsi:nil="true"></CVDCode>
<CVD_Presence_Ind xsi:type="xsd:string">0</CVD_Presence_Ind>
<ZipCode xsi:nil="true"></ZipCode>
<Tax1Amount xsi:nil="true"></Tax1Amount>
<Tax1Number xsi:nil="true"></Tax1Number>
<Tax2Amount xsi:nil="true"></Tax2Amount>
<Tax2Number xsi:nil="true"></Tax2Number>
<Ecommerce_Flag xsi:type="xsd:string">0</Ecommerce_Flag>
<XID xsi:nil="true"></XID>
<CAVV xsi:nil="true"></CAVV>
<CAVV_Algorithm xsi:nil="true"></CAVV_Algorithm>
<Reference_No xsi:nil="true"></Reference_No>
<Customer_Ref xsi:nil="true"></Customer_Ref>
<Reference_3 xsi:nil="true"></Reference_3>
<Language xsi:nil="true"></Language>
<Client_IP xsi:type="xsd:string">10.1.1.20</Client_IP>
<Client_Email xsi:nil="true"></Client_Email>
<LogonMessage xsi:nil="true"></LogonMessage>
<Error_Number xsi:type="xsd:string">0</Error_Number>
<Error_Description xsi:nil="true"> </Error_Description>
<Transaction_Error xsi:type="xsd:boolean">false</Transaction_Error>
<Transaction_Approved xsi:type="xsd:boolean">true</Transaction_Approved>
<EXact_Resp_Code xsi:type="xsd:string">00</EXact_Resp_Code>
<EXact_Message xsi:type="xsd:string">Transaction Normal</EXact_Message>
<Bank_Resp_Code xsi:type="xsd:string">000</Bank_Resp_Code>
<Bank_Message xsi:type="xsd:string">APPROVED</Bank_Message>
<Bank_Resp_Code_2 xsi:nil="true"></Bank_Resp_Code_2>
<SequenceNo xsi:type="xsd:string">025849</SequenceNo>
<AVS xsi:nil="true"></AVS>
<CVV2 xsi:nil="true"></CVV2>
<Retrieval_Ref_No xsi:type="xsd:string">08184653</Retrieval_Ref_No>
<CAVV_Response xsi:nil="true"></CAVV_Response>
<MerchantName xsi:type="xsd:string">Ralph's</MerchantName>
<MerchantAddress xsi:type="xsd:string">127 Quintana St</MerchantAddress>
<MerchantCity xsi:type="xsd:string">Venice</MerchantCity>
<MerchantState xsi:type="xsd:string">California</MerchantState>
<MerchantCountry xsi:type="xsd:string">US</MerchantCountry>
<MerchantPostal xsi:type="xsd:string">90291</MerchantPostal>
<MerchantURL xsi:type="xsd:string">www.firstdata.com</MerchantURL>
<CTR xsi:type="xsd:string">=========== TRANSACTION RECORD ==========
API Testing
127 Quintana St
Venice, CA 90291
US
www.firstdata.com

TYPE: Pre-Authorization

ACCT: Visa $ 15.75 USD

CARD NUMBER : ############1111
DATE/TIME : 18 Aug 10 09:46:52
REFERENCE # : 002 025849 M
AUTHOR. # : ET4653
TRANS. REF. :

Approved - Thank You 000


Please retain this copy for your records.

Cardholder will pay above amount to card
issuer pursuant to cardholder agreement.
=========================================</CTR>
</types:TransactionResult>
</soap:Body>
</soap:Envelope>

7.2 Example 2. Tagged Pre-Authorization Completion

This request illustrates the following:

  • using the REST Payeezy Gateway Web Service API with XML message format
  • passing authentication credentials in the message as ExactID and Password properties
  • completing the Pre-Authorization transaction from Example 1 using the response properties from that transaction
curl -H 'Content-Type: application/xml; charset=UTF-8' \

-H 'Accept: application/xml' \
-d '<?xml version="1.0" encoding="UTF-8"?>
<Transaction>
<ExactID>ExactID</ExactID>
<Password>Password</Password>
<Transaction_Type>32</Transaction_Type>
<Transaction_Tag>901975484</Transaction_Tag>
<Authorization_Num>ET4653</Authorization_Num>
<DollarAmount>15.75</DollarAmount>
</Transaction>' \
https://api.globalgatewaye4.firstdata.com/transaction

The resulting request headers and response:

POST /transaction HTTP/1.1
User-Agent: curl/7.21.0 (i386-apple-darwin9.8.0) libcurl/7.21.0 OpenSSL/1.0.0a zlib/1.2.5 libidn/1.19
Host:
Content-Type: application/xml; charset=UTF-8
Accept: application/xml
Content-Length: 304

HTTP/1.1 201 Created
Date: Wed, 18 Aug 2010 19:39:51 GMT
Server: Apache
Cache-Control: no-cache
Location: https://api.globalgatewaye4.firstdata.com/transaction/v8.xml/902006933
Content-Length: 2573
Status: 201
Content-Type: application/xml; charset=utf-8
Vary: Accept-Encoding

<?xml version="1.0" encoding="UTF-8"?>
<TransactionResult>
<ExactID>ExactID</ExactID>
<Password></Password>
<Transaction_Type>32</Transaction_Type>
<DollarAmount>15.75</DollarAmount>
<SurchargeAmount></SurchargeAmount>
<Card_Number>############1111</Card_Number>
<Transaction_Tag>902006933</Transaction_Tag>
<Track1></Track1>
<Track2></Track2>
<PAN></PAN>
<Authorization_Num>ET4653</Authorization_Num>
<Expiry_Date>1016</Expiry_Date>
<CardHoldersName>Uli Kunkel</CardHoldersName>
<Address></Address>
<CVDCode></CVDCode>
<CVD_Presence_Ind>0</CVD_Presence_Ind>
<ZipCode></ZipCode>
<Tax1Amount></Tax1Amount>
<Tax1Number></Tax1Number>
<Tax2Amount></Tax2Amount>
<Tax2Number></Tax2Number>
<Ecommerce_Flag>0</Ecommerce_Flag>
<XID></XID>
<CAVV></CAVV>
<CAVV_Algorithm></CAVV_Algorithm>
<Reference_No></Reference_No>
<Customer_Ref></Customer_Ref>
<Reference_3></Reference_3>
<Language></Language>
<Client_IP>10.1.1.20</Client_IP>
<Client_Email></Client_Email>
<LogonMessage></LogonMessage>
<Error_Number>0</Error_Number>
<Error_Description> </Error_Description>
<Transaction_Error>false</Transaction_Error>
<Transaction_Approved>true</Transaction_Approved>
<EXact_Resp_Code>00</EXact_Resp_Code>
<EXact_Message>Transaction Normal</EXact_Message>
<Bank_Resp_Code>000</Bank_Resp_Code>
<Bank_Message>APPROVED</Bank_Message>
<Bank_Resp_Code_2></Bank_Resp_Code_2>
<SequenceNo>025850</SequenceNo>
<AVS></AVS>
<CVV2></CVV2>
<Retrieval_Ref_No>08183837</Retrieval_Ref_No>
<CAVV_Response></CAVV_Response>
<MerchantName>API Testing</MerchantName>
<MerchantAddress>127 - 6768 Front St</MerchantAddress>
<MerchantCity>Vancouver</MerchantCity>
<MerchantProvince>British Columbia</MerchantProvince>
<MerchantCountry>Canada</MerchantCountry>
<MerchantPostal>V6B 2H7</MerchantPostal>
<MerchantURL>www.firstdata.com</MerchantURL>
<CTR>=========== TRANSACTION RECORD ==========
API Testing
127 - 6768 Front St
Vancouver, BC V6B 2H7
Canada
www.firstdata.com

TYPE: Pre-Auth Completion

ACCT: Visa $ 15.75 CAD

CARD NUMBER : ############1111
DATE/TIME : 18 Aug 10 11:38:36
REFERENCE # : 002 025850 M
AUTHOR. # : ET4653
TRANS. REF. :

Approved - Thank You 000


Please retain this copy for your records.

Cardholder will pay above amount to card
issuer pursuant to cardholder agreement.
=========================================</CTR>
</TransactionResult>

7.3 Example 3. Tagged Refund

This request illustrates the following:

  • using the REST Payeezy Gateway Web Service API with JSON message format
  • passing authentication credentials as HTTP Basic Authentication username:password values
  • refunding the Tagged Pre-Authorization Completion transaction from Example 2 using the response properties from that transaction
curl -u 'ExactID:Password' \

-H 'Content-Type: application/json; charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"transaction_type":"34",
"transaction_tag":"902006933",
"authorization_num":"ET4653",
"amount":"15.75"
}' \
https://api.globalgatewaye4.firstdata.com/transaction

The resulting request headers and response:

POST /transaction HTTP/1.1
Authorization: Basic Foo4BarBazAyOjAhcGl0ZXN0
User-Agent: curl/7.21.0 (i386-apple-darwin9.8.0) libcurl/7.21.0 OpenSSL/1.0.0a zlib/1.2.5 libidn/1.19
Host: api.globalgatewaye4.firstdata.com
Content-Type: application/json; charset=UTF-8
Accept: application/json
Content-Length: 110

HTTP/1.1 201 Created
Date: Wed, 18 Aug 2010 19:52:18 GMT
Server: Apache
Cache-Control: no-cache
Location: https://api.globalgatewaye4.firstdata.com/transaction?amount=15.75&...
Content-Length: 1713
Status: 201
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding

{"merchant_url":"www.firstdata.com",
"cc_number":"############1111",
"secure_auth_required":null,
"cc_cvd_code":null,
"zip_code":null,
"user_name":null,
"reference_no":null,
"cc_expiry":"1012",
"avs":null,
"client_email":null,
"secure_auth_result":null,
"cavv_response":null,
"bank_resp_code":"000",
"password":null,
"merchant_address":"127 Jam St",
"transaction_tag":902010341,
"cardholder_name":"Jackie Treehorn",
"retrieval_ref_no":"08185104",
"gateway_id":"ExactID",
"merchant_country":"US",
"error_description":" ",
"bank_message":"APPROVED",
"cavv":null,
"track1":null,
"tax1_amount":null,
"reference_3":null,
"surcharge_amount":null,
"transaction_type":"34",
"ctr":"=========== TRANSACTION RECORD ==========\nAPI Testing\n127 - 6768 Front St\nVancouver, BC V6B 2H7\nCanada\nwww.firstdata.com\n\nTYPE: Refund\n\nACCT: Visa $ 15.75 CAD\n\nCARD NUMBER : ############1111\nDATE/TIME : 18 Aug 10 11:51:03\nREFERENCE # : 002 025851 M\nAUTHOR. # : RETURN\nTRANS. REF. : \n\n Approved - Thank You 000\n\n\nPlease retain this copy for your records.\n\n=========================================",
"ecommerce_flag":0,
"bank_resp_code_2":null,
"language":null,
"merchant_city":"Malibu",
"logon_message":null,
"tax2_amount":null,
"track2":null,
"transaction_approved":1,
"merchant_postal":"90263",
"transaction_error":0,
"cvd_presence_ind":0,
"xid":null,
"pan":null,
"tax1_number":null,
"exact_resp_code":"00",
"customer_ref":null,
"amount":15.75,
"cavv_algorithm":null,
"cvv2":null,
"cc_address":null,
"sequence_no":"025851",
"merchant_name":"API Testing",
"client_ip":"10.1.1.20",
"merchant_state":"California",
"error_number":0,
"tax2_number":null,
"authorization_num":"RETURN",
"exact_message":"Transaction Normal"}

8 Exception Handling

The Payeezy Gateway Web Service API may return error messages in two different forms. An error message is either returned as a Soap Exception or as Response - Error Properties. Various levels of detail are returned with each. The content of each error type is detailed in the follow sections.

8.1 SOAP Exception

SOAP exceptions may be encountered for two broad reasons. One, if a SOAP message is malformed. Two, if the Web Service experiences some sort of general system failure. The SOAP Exception Scenarios section below provides examples for various error scenarios.

Any SOAP exception generated will conform to the SOAP 1.1 protocol. A SOAP exception will contain the following values (elements or attributes).

faultcode
  • String [var]
  • {Read} {minOccurs="1" maxOccurs="1"}
The faultcode will contain one of the following values:
  • VersionMismatch : The processing part found an invalid namespace for the SOAP Envelope element.
  • Client : The Client class or errors indicate that the message was incorrectly formed or did not contain the appropriate information in order to succeed. It is a general indication that the message should not be resent without change.
  • Server : The Server class or errors indicate that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to the processing of the message. The message may succeed at a later point in time.

Client and Server are the most common values returned.

faultstring
  • String [var]
  • {Read} {minOccurs="1" maxOccurs="1"}
A system generated text description of the error.
faultactor
  • String [var]
  • {Read} {minOccurs="0" maxOccurs="1"}
The URL of the Web Service. This value is only returned under certain circumstances. The value is generally not returned if an error occurs before or during the deserializing of the SOAP message. The value is generally returned if an error occurs after deserializing the SOAP message.
detail
  • Element
  • {Read} {minOccurs="1" maxOccurs="1"}

The detail element is always returned. The detail element may or may not contain details of the error. If details of the error are returned, they will be contained in a child “error” element.

The “error” element is generally not returned if an error occurs before or during the deserializing of the SOAP message. The error element is generally returned if an error occurs after deserializing the SOAP message.

And example of the detail element containing an error element is as follows:

If an “error” element is returned, it will contain the attributes “number”, “description” and “xmlns”. The possible values of the “number” and “description” attributes are described in First Data Payeezy Gateway Web Service API Error Numbers and Descriptions.

8.2 SOAP Exception Scenarios

In example 6.1, a SOAP Exception is shown for a malformed incoming SOAP request. This type or error message format generally occurs when an error is encountered before or during deserialization of an incoming SOAP message. This type of error requires the request to be modified before being sent again.

Example 6.1 SOAP Exception for a Malformed Incoming SOAP Message

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Server was unable to read request. --&gt; There is an
error in XML document (1, 406). --&gt; &amp;lt;SendAndCommit
xmlns='http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-
enc/'&amp;gt; was not expected.</faultstring>
<detail />
</soap:Fault>
</soap:Body>
</soap:Envelope>

In example 6.2, a SOAP Exception is shown for an incoming SOAP request containing a null Transaction struct. This message format generally occurs when an error is encountered after deserialization of an incoming SOAP message. This type of error requires the request to be modified before being sent again.

Example 6.2 SOAP Exception for an Incoming SOAP Message Containing a Null Transaction

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>System.Web.Services.Protocols.SoapException: Setup Error at
rpc-enc.Service.SendAndCommit(Transaction Transaction) in C:\Documents
and Settings\defaultuser\VSWebCache\api.globalgatewaye4.firstdata.com\vplug-
in\transaction\rpc-enc\Service.asmx.vb:line 98</faultstring>
<faultactor>http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-
enc/Service.asmx</faultactor>
<detail>
<error number="400" description="Bad Request. Object reference not set
to an instance of a Transaction object." xmlns="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc" />
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

In example 6.3, a SOAP Exception is shown for a general system failure. This message format generally occurs when an error is encountered after deserializing a SOAP message. This type of error usually results from an internal problem within the Payeezy Gateway Web Service API. The same request may work if sent at a later time.

Example 6.3 SOAP Exception for a General System Failure Within the Web Service

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>System.Web.Services.Protocols.SoapException: Setup Error at
rpc-enc.Service.SendAndCommit(Transaction Transaction) in C:\Documents
and Settings\defaultuser\VSWebCache\api.globalgatewaye4.firstdata.com\vplug-
in\transaction\rpc-enc\Service.asmx.vb:line 99</faultstring>
<faultactor>http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-
enc/Service.asmx</faultactor>
<detail>
<error number="500" description="Internal Server Error. An unknown
error occurred." xmlns="http://api.globalgatewaye4.firstdata.com/vplug-
in/transaction/rpc-enc" />
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>

8.3 Response - Error Properties

If an incoming message is successfully received but the transaction not successfully processed, various error indicator properties are returned in the response. The properties may define three broad types of failure.

One, the error properties may indicate that invalid values were sent in the request. Two, the error properties may indicate that some sort of failure occurred while processing the transaction. Three, the error properties may indicate that the transaction was processed normally but still declined. (This is in fact not an actual error. It is described here, as the Merchant’s system may want to treat normal declines as a type of failure.)

An occurrence of the first error type is reflected in the following property values being returned:

Error_Number error number
Error_Description error description
Transaction_Error "False"
Transaction_Approved "False"

The error number and error description values that may be returned are defined in First Data Payeezy Gateway Web Service API Error Numbers and Descriptions.

An occurrence of the second error type is reflected in the following property values being returned:

Error_Number "0"
Error_Description null
Transaction_Error "True"
Transaction_Approved "False"
Exact_Resp_code error code
Exact_Message error message

The error code and error message values that may be returned are defined in eCommerce Response Codes (ETG [Payeezy Gateway Transaction Gateway] Codes).

An occurrence of the third error type is reflected in the following property values being returned:

Error_Number "0"
Error_Description null
Transaction_Error "False"
Transaction_Approved "False"
Exact_Resp_code "00"
Exact_Message "Transaction Normal"
Bank_Resp_code bank response code
Bank_Message bank response message
Bank_Resp_code_2 bank response code 2 (usually null)

The error code and error message values that may be returned are defined in Payeezy Gateway Bank Response Codes.

9 API HMAC Security (V12+)

Those merchants wishing to use V12 or V13 of the API must implement the API HMAC hash security calculation. Further information on this subject can be found here.

 

Appendix 1. More About Service URLs

NOTE:There is a known bug in the API in Version 9, where the VirtualCard element is specified as type Boolean in the WSDL, but returned as type String in the SOAP response. This will most likely cause an issue in .Net clients which use proxy classes automatically generated based on the WSDL. The workaround is to manually update the type definition for VirtualCard in the automatically generated class.,

Clients using the REST flavor of the API should not be affected by this bug.

Below is a comprehensive list of the service URLs:

 

Version 22
Version 21
Version 20
  • This version was skipped.
Version 19
Version 18
Version 17
Version 16
Version 15
Version 14
Version 13
Version 12
Version 11
Version 10
Version 9
Version 8
Version Changes
V8 Base version
V9

Added Properties: CardCost, TransarmorToken, CardType, EAN, VirtualCard, Level 3 Properties, Debit Bill Pay

Added Transaction Types: 83, 85, 86, 88, 89

Other changes: minOccurs/maxOccurs update, TransArmor support, Valuelink support, Level 3 support

Removed Properties: LogonMessage, ErrorNumber and ErrorDescription

V10

Added Properties: PaypalTransactionDetails, PayerID, GrossAmountCurrencyID, Success, Authorization, Message, CorrelationID, Timestamp

Other changes: PayPal Order Support

V11

Added Properties: SoftDescriptor, DBAName, Street, City, Region, PostalCode, CountryCode, MID, MCC, MerchantContactInfo

V12

Added Properties: FraudSuspected

Other changes: HMAC authentication support

V13

Added TeleCheck support

V14

Replaced Property:

VerificationStr1 replaced with Address element

VerificationStr2 replaced with CVDCode

Added Property: SplitTenderID, TPPID

 

V15

Added Property: SplitShipmentNumber

V16

Added support for Amex Fraud Mitigation Reply Format Indicators

 

V17

Added support for DCC and DP

 

V18  Added support for Fees
V19 Added support for Visa Checkout (VCO)
V20 This version was skipped
V21 Added support for Special Payments
V22 Added support for wallet_provider_id
Powered by Zendesk