Forums/Web Service API and other Ways to Get Your Data

First Data Global Gateway e4℠ Web Service API Reference Guide

First Data Support (LL)
posted this on January 20, 2011 13:30

 

1 Intended Audience

This document is intended for

  • Developers who want to understand and implement the First Data Global Gateway e4℠ web service API

2 Introduction

The First Data Global Gateway e4℠ web service API is a web service that allows third-party applications to process transactions through the Global Gateway e4℠ 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 Global Gateway e4℠ web service API. 

The Global Gateway e4℠ 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 Global Gateway e4℠ web service API you choose.

 

IMPORTANT NOTE: ALL TAGS MUST 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 bugs. You can find this in section 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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠ web service API message via the ExactID and Password properties

The Gateway ID can be found under 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.

terminal.png 

 

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

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 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 Global Gateway e4 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 Global Gateway e4 Web Service API or Hosted Payment Pages, can be utilized within the e4 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 Global Gateway E4 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. 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
  • ValueLink is supported only through the GGe4 Web API interface (integration). It is not supported through RPM or HCO (Hosted Checkout).
  • GGe4 is certified SVdot Internet message format through Compass host.
  • Currently, only the ValueLink Premium gift card program is supported. Contact your First Data representative for more information if you would like to include this payment solution. 
  • ValueLinkk has the ability support partial approval. Approved Amount will be returned and the Integrator will be responsible for handling the request for additional form 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")

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 to 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

Verification_Str1

Void 13

DollarAmount

CheckNumber

CheckType

CustomerName

BankAccountNumber

BankRoutingNumber

CustomerIDType

CustomerID

Client_Email

Verification_Str1

Authorization_Num

Tagged Void 33

Transaction_Tag

DollarAmount

Authorization_Num

Tagged Refund 34

Transaction_Tag

DollarAmount

Authorization_Num

 Updated 02/03/14 MW

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 GGe4, 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

Note: when submitting information for Telecheck transactions in this field, this format should be used:

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

The "Phone" value should be prepended with the letter D, H, N, or W for day, home, night, and work respectively. For example, "H5555555555".

Required Character Format is ASCII.

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.
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 Global Gateway e4℠ unmodified, and may be searched in First Data Global Gateway e4℠ 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

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

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.

Global Gateway e4SM 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.

Global Gateway e4SM 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.

Global Gateway e4SM 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.

Global Gateway e4SM 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 Global Gateway e4℠ unmodified, and may be searched in First Data Global Gateway e4℠ 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 Global Gateway e4℠ 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. This property can only be used with the v9 or higher endpoint of the API.

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.

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. This property can only be used with the v9 or higher endpoint of the API.

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 Card", "PayPal"

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 v13 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 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 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 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 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 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 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 endpoint.

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

Global Gateway e4SM 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.

Global Gateway e4SM 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.

Global Gateway e4SM 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.

Global Gateway e4SM 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 Global Gateway e4℠ unmodified,   and may be searched in First Data Global Gateway e4℠   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.2 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.

 Global Gateway e4SM 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 using American Express, it  must be enabled on your merchant account. Please contact your First Data Sales Representative for more details.

 

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.3 PayPal Properties

The following PayPal properties are used to record PayPal transactions that have already been processed into the Global Gateway e4 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

 PaypalResponse

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

Global Gateway e4 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 Global Gateway e4 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. GGe4 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 GGe4 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://www.x.com/developers/paypal/documentation-tools/quick-start-guides/express-checkout-api

 

 GGe4 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.4 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, v12 and v13 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 at authorization and at 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".

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.5 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. This property is only applicable to the v13 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 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 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 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 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 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 endpoint.

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.

 

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

6 SOAP Message Format

The SOAP style Global Gateway e4℠ 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 Global Gateway e4℠ 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 at http://www.w3.org/TR/2000/NOTE-SOAP-20000508.

6.1 Request Message Format

The Global Gateway e4℠ 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>
      <VerificationStr1 xsi:type="xsd:string">string</VerificationStr1>
      <VerificationStr2 xsi:type="xsd:string">string</VerificationStr2>
      <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>
      <VerificationStr1 xsi:type="xsd:string">string</VerificationStr1>
      <VerificationStr2 xsi:type="xsd:string">string</VerificationStr2>
      <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>
      <VerificationStr1 xsi:type="xsd:string">string</VerificationStr1>
      <VerificationStr2 xsi:type="xsd:string">string</VerificationStr2>
      <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 Global Gateway e4℠ 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>
      <VerificationStr1 xsi:nil="true"></VerificationStr1>
      <VerificationStr2 xsi:nil="true"></VerificationStr2>
      <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 Global Gateway e4℠ 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>
  <VerificationStr1></VerificationStr1>
  <VerificationStr2></VerificationStr2>
  <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 Global Gateway e4℠ 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_verification_str2":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_verification_str1":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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 Global Gateway e4℠ 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 [e4 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 Global Gateway e4℠ 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 13
Version 12
Version 11
Version 10
Version 9
Version 8
Version WSDL Changes
V8 Base version
V9

Added Properties: CardCost, TransarmorToken, CardType, EAN, VirtualCard, Level 3 Properties 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

Updated 10/23/13 MW

 
Topic is closed for comments