First Data Payeezy Gateway Web Service API Reference Guide

  • 1 Intended Audience

    This document is intended for

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

    2 Introduction

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

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

     

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

    2.1 Basic Information

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

    The service URLs are:

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

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

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

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

    These credentials can be submitted in two ways:

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

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

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

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

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

    Password Generation/Use:

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

    For carts that do not accept 32 characters

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

    3 API 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

    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. Note: Payeezy Gateway only supports the NVP/SOAP API.

    Transaction Name Transaction Type Required Properties
    Order 07

    CardHoldersName

    DollarAmount

    Authorization

    PayerID

    Success

    CorrelationID

    Message

    CardType (set to "PayPal")

    Pre-Authorization 01

    CardHoldersName

    DollarAmount

    Authorization

    PayerID

    Success

    CorrelationID

    Message

    CardType (set to "PayPal")

    Purchase 00

    CardHoldersName

    DollarAmount

    Authorization

    PayerID

    Success

    CorrelationID

    Message

    CardType (set to "PayPal")

    Tagged Completion 32

    Transaction_Tag

    DollarAmount

    Tagged Void 33

    Transaction_Tag

    DollarAmount

    Tagged Refund 34

    Transaction_Tag

    DollarAmount

     

    3.2 Zero Dollar Pre-Authorizations

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

    3.3 Gift Cards (ValueLink) Transactions

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

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

       

      Example:

       

      TYPE: Purchase

       

      ACCT: Gift Card $ 50.00 USD

      ($ 62.00 was requested)

       

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

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

      REFERENCE # : 001 0159477 M

      AUTHOR. # : 1

      TRANS. REF. :

       

      Approved - Thank You 100

    Transaction Name Transaction Type Required Properties
    Purchase

    00

    CardHoldersName

    Card_Number

    DollarAmount

    CardType (set to "Gift")

    Refund

    04

    CardHoldersName

    Card_Number

    DollarAmount

    CardType (set to "Gift")

    Authorization_Num

    Void

    13

    CardHoldersName

    Card_Number

    DollarAmount

    CardType (set to "Gift")

    Authorization_Num

    Tagged Void

    33

    Transaction_Tag

    DollarAmount

    Authorization_Num

    CardType (set to "Gift")

    Tagged Refund

    34

    Transaction_Tag

    DollarAmount

    Authorization_Num

    CardType (set to "Gift")

    CashOut

    83

    CardHoldersName

    Card_Number

    CardType (set to "Gift")

    ValueLink Activation

    85

    CardHoldersName

    Card_Number

    DollarAmount

    CardCost

    CardType (set to "Gift")

    Balance Inquiry

    86

    CardHoldersName

    Card_Number

    CardType (set to "Gift")

    Reload

    88

    CardHoldersName

    Card_Number

    CardType (set to "Gift")

    DollarAmount

    ValueLink Deactivation

    89

    CardHoldersName

    Card_Number

    CardType (set to "Gift")

     

    Example ValueLink Activate Virtual Card

     

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

     

    Activation Request:


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

     

    Activation Response:

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

    3.4 TransArmor Transactions

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

    Transaction Name

    Transaction Type

    Required Properties

    Purchase

    00

    CardHoldersName

    TransarmorToken

    DollarAmount

    CardType

    Expiry_Date

    Pre-Authorization

    01

    CardHoldersName

    TransarmorToken

    DollarAmount

    CardType

    Expiry_Date

    Forced Post

    03

    CardHoldersName

    TransarmorToken

    DollarAmount

    CardType

    Authorization_Num

    Expiry_Date

    Refund

    04

    CardHoldersName

    TransarmorToken

    DollarAmount

    CardType

    Expiry_Date

    Pre-Authorization Only

    05

    CardHoldersName

    TransarmorToken

    DollarAmount

    CardType

    Expiry_Date

    Void

    13

    CardHoldersName

    TransarmorToken

    DollarAmount

    CardType

    Authorization_Num

    Expiry_Date

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

    <TransactionResult>

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

    <Expiry_Date>0412</Expiry_Date>

    <EXact_Resp_Code>00</EXact_Resp_Code>

    <EXact_Message>Transaction Normal</EXact_Message>

    <Bank_Resp_Code>100</Bank_Resp_Code>

    <Bank_Message>Approved</Bank_Message>

    <Bank_Resp_Code_2></Bank_Resp_Code_2>

    <SequenceNo>0000165</SequenceNo>

    ….

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

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

    Using TransArmor Tokens with a Test Account

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

     

    3.5 Telecheck Transactions

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

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

     

    Transaction Name Transaction Type Required Properties
    Purchase 00

    DollarAmount

    CheckNumber

    CheckType

    CustomerName

    BankAccountNumber

    BankRoutingNumber

    CustomerIDType

    CustomerID

    Client_Email

    Address

    Void 13

    DollarAmount

    CheckNumber

    CheckType

    CustomerName

    BankAccountNumber

    BankRoutingNumber

    CustomerIDType

    CustomerID

    Client_Email

    Address

    Authorization_Num

    Tagged Void 33

    Transaction_Tag

    DollarAmount

    Authorization_Num

    Tagged Refund 34

    Transaction_Tag

    DollarAmount

    Authorization_Num

    Updated 02/03/14 MW

     

    3.6 Visa Checkout Transactions

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

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

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

     

    Branding of the Visa Checkout button

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

     

    Visa Checkout Asset Inventory

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

     

    Visa Checkout Buttons

    Standard button without card art:

    Neutral button without card art:

    Button with card art:

     

    Visa Checkout Acceptance Marks

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

     

    General Visa Checkout Asset Placement and Usage Requirements

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

     

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

     

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

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

     

    Visa Checkout Button Requirements

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

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

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

     

    Visa Checkout Acceptance Mark Requirements

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

     

    • Preferred acceptance mark, 99x34 pixels:

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

     

    • 40x30 pixels:

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

     

    • 49x31 pixels:

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

     

    • 28x21 pixels:

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

     

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

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

     

    Use on Payment Pages

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

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

     

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

     

    Identifying Accepted Payment Methods

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

     

    Visa Checkout Messaging

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

     

    Short Statement

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

     

    Long Statement

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

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

     

    Placement of the Visa Checkout button

     

    Visa Checkout JavaScript and Button Reference sdk.js JavaScript Library

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

     

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

    Example

    <body>

    ...

    <script type="text/javascript"

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

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

    </script>

    </body>

     

    v-button Image Class

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

     

    Query Parameters

    Parameter

    Description

    size

    (Optional) Width of the button, in pixels.

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

     

    Format: It is one of the following values:

    • 154 - small

    • 213 - medium (default)

    • 425 - High resolution or large

    Any other value defaults to 213 pixels.

     

    Example: size=154

    Since 2.0

    height

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

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

     

    Format: It is one of the following values:

    • 34

    • 47

    • 94

     

    Example: height=94

    Since 2.4

    width

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

     

    Format: It is one of the following values:

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

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

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

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

     

    Example: width=200

    Since 2.4

    locale

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

     

    Format: It is one of the following values:

    • en_US - American English

    • en_CA - Canadian English

    • fr_CA - Canadian French

    • en_AU - Australian English

     

    Example: locale=en_US

    Since 2.0

    color

    (Optional) The color of the Visa Checkout button.

     

    Format: It is one of the following values:

    • standard (default)

    • neutral

     

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

     

    Example: color=neutral

    Since 2.5

    cardBrands

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

     

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

    • VISA

    • MASTERCARD

    • AMEX

    • DISCOVER

     

    Example: cardBrands=VISA,AMEX

    Since 2.0

    acceptCanadianVisaDebit

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

     

    Format: One of the following values:

    • true - Visa Canada debit cards accepted

    • false - Visa Canada debit cards not accepted

     

    Example: acceptCanadianVisaDebit : "true"

    Since 2.0

     

     

    Examples

    <body>

    ...

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

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

    />

    ...

    </body>

     

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

     

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

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

    />

     

     

    onVisaCheckoutReady Function

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

    Event Handler

    Description

    V.init

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

    Since 2.0

    V.on

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

    • payment.success

    • payment.cancel

    • payment.error

    Since 2.0

     

    Example

    <head>

    ...

    <script type="text/javascript">

    function onVisaCheckoutReady(){

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

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

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

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

    }

    </script>

    ...

    </head>

     

     

    V.init Event Handler

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

    Property

    Description

    apikey

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

     

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

     

    Format: Alphanumeric; maximum 100 characters

    Since 2.0

    externalProfileId

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

     

    Format: Alphanumeric; maximum 50 characters

    Since 2.0

    externalClientId

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

     

    Format: Alphanumeric; maximum 100 characters

    Since 2.0

    sourceId

    (Optional) Your merchant reference ID.

     

    Format: Alphanumeric; maximum 100 characters

    Since 2.0

    settings

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

     

    Format: settings=xxxxx?

    Since 2.0

    paymentRequest

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

     

    Format: paymentRequest=xxxx?

    Since 2.0

     

     

    Settings Properties

    Property

    Description

    locale

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

     

    Format: It is one of the following values:

    • en_US - American English

    • en_CA - Canadian English

    • fr_CA - Canadian French

    • en_AU - Australian English

     

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

    Since 2.0

    countryCode

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

     

    Format: It is one of the following values:

    • US - United States

    • CA - Canada

    • AU - Australia

     

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

    Since 2.0

    logoUrl

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

     

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

     

    Format: HTTPS URL; maximum 256 characters

    Since 2.0

    displayName

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

     

    Format: Alphanumeric

    Since 2.0

    websiteUrl

    (Optional) Complete URL to your website.

     

    Format: Valid URL, beginning with HTTP

    Since 2.0

    customerSupportUrl

    (Optional) Your complete customer service or support URL.

     

    Format: Valid URL, beginning with HTTP

    Since 2.0

    shipping

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

     

    Format: shipping

    Since 2.0

    review

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

     

    Format: review

    Since 2.0

    payment

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

    Format: payment

    Since 2.0

    dataLevel

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

     

    Format: It is one of the following values:

    • SUMMARY - Summary information (default)

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

    Since 2.0

     

     

    Lightbox Panel Configuration Example

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

    V.init({

    ...

    settings: {

    locale: "en_US",

    countryCode: "US",

    displayName: "MegaCorp",

    logoUrl: "www.Some_Image_URL.gif",

    websiteUrl: "www.MegaCorp.com",

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

    ...

    dataLevel: "FULL"

    ...

    );

     

    Shipping Properties

    Property

    Description

    acceptedRegions

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

     

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

    Since 2.0

    collectShipping

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

     

    Format: One of the following values:

    • true - Obtain shipping address (default)

    • false - Shipping address is not required

    Since 2.0

     

    Shipping Options Configuration Example

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

    V.init({

    ...

    settings: {

    ...

    shipping: {

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

    collectShipping: "true"

    },

    ...

    );

     

     

    Review Properties

    Property

    Description

    message

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

     

    Format: Alphanumeric; maximum 120 characters

    Since 2.0

    buttonAction

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

     

    Format: One of the following values:

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

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

    Since 2.0

     

     

    Review Options Configuration Example

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

    review: {

    message: "Merchant defined message",

    buttonAction: "Continue"

    },

     

    Payment Properties

    Property

    Description

    cardBrands

    (Optional) Card brands that are accepted.

     

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

    • VISA

    • MASTERCARD

    • AMEX

    • DISCOVER

    Since 2.0

    acceptCanadianVisaDebit

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

     

    Format: One of the following values:

    • true - Visa Canada debit cards accepted

    • false - Visa Canada debit cards not accepted

     

    Example: acceptCanadianVisaDebit : "true"

    Since 2.0

     

     

    Payment Options Configuration Example

    You can limit the kind of cards you accept:

    V.init({

    ...

    settings: {

    ...

    payment: {

    cardBrands: [

    "VISA",

    "MASTERCARD"],

    acceptCanadianVisaDebit : "true"

    },

    ...

    },

    ...

    );

     

     

    Payment Request Properties

    Property

    Description

    merchantRequestId

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

     

    Format: Alphanumeric; maximum 100 characters

    Since 2.0

    currencyCode

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

     

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

    • USD - US dollars

    • CAD - Canadian dollars

    • AUD - Australian dollars

    Currency codes must be uppercase.

     

    Example: "currencyCode" : "USD"

    Since 2.0

    subtotal

    (Required) Subtotal of the payment.

     

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

     

    Example: "subtotal" : "9.00"

    Since 2.0

    shippingHandling

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

     

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

     

    Example: "shippingHandling" : "3.00"

    Since 2.0

    tax

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

     

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

     

    Example: "tax" : "1.00"

    Since 2.0

    discount

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

     

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

     

    Example: "discount" : "2.50"

    Since 2.0

    giftWrap

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

     

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

     

    Example: "giftWrap" : "1.99"

    Since 2.0

    misc

    (Optional) Total uncategorized charges in the payment.

     

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

     

    Example: "misc" : "1.00"

    Since 2.0

    total

    (Optional) Total of the payment including all amounts.

     

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

     

    Example: "total" : "9.00"

    Since 2.0

    orderId

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

    Format: Alphanumeric; maximum 100 characters

    Since 2.0

    promoCode

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

     

    Format: Alphanumeric; maximum 100 characters

     

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

    Since 2.0

    customData

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

     

    Format: Alphanumeric; maximum 1024 characters

     

    Example:

    customData: {

    "nvPair": [

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

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

    ] ...

     

    Since 2.0

     

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

    Value of the transaction (USD only)

    Value of advice in the response

    Value of score in the response

    0.01 to 0.99

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

    UNAVAILABLE

    0

    1.00 to 49.99

    LOW

    10

    50.00 to 149.99

    MEDIUM

    45

    150.00 or more

    HIGH

    90

     

    Payment Request Configuration Example

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

    V.init({

    ...

    paymentRequest: {

    merchantRequestId: "Merchant defined request ID",

    currencyCode: "USD",

    subtotal: "10.00",

    shippingHandling: "2.00",

    tax: "2.00",

    discount: "1.00",

    giftWrap: "2.00",

    misc: "1.00",

    total: "16.00",

    description: "Megacorp Product",

    orderId: "Merchant defined order ID",

    promoCode: "Merchant defined promo code",

    customData: {

    "nvPair": [

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

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

    ]

    ...

    );

     

     

    Response to Payment Success Events

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

    Property

    Description

    callId

    Visa Checkout transaction ID, which represents the purchase.

     

    Format: Numeric; maximum 20 digits

     

    Example: "callId":"..."

    Since 2.0

    responseStatus

    Response status.

     

     

     

    encKey

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

     

    Format: Alphanumeric; maximum 128 characters

     

    Example: "encKey":"..."

    Since 2.0

    encPaymentData

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

     

    Format: Alphanumeric; maximum 1024 characters

     

    Example: "encPaymentData":"..."

    Since 2.0

    externalClientId

    Merchant ID of the merchant receiving the payment.

     

    Format: Alphanumeric; maximum 100 characters

    Since 2.0

    partialShippingAddress

    Partial shipping address of the consumer.

     

    Format: Partial shipping address structure

    Since 2.0

     

     

    Response Status

    Property

    Description

    status

    HTTPS response status.

     

    Format: Numeric

    Since 2.0

    code

    Internal subcode.

     

    Format: Numeric

    Since 2.0

    severity

    Severity of the error.

     

    Format: It is one of the following values:

    • ERROR

    • WARNING

    Since 2.0

    message

    Description of the error.

     

    Format: Alphanumeric

    Since 2.0

     

     

    Partial Shipping Address

    Property

    Description

    countryCode

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

     

    Format: Alphanumeric; maximum 2 characters

    Since 2.0

    postalCode

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

     

    Format: Alphanumeric; maximum 128 characters

    Since 2.0

     

     

    Response to Payment Cancelled Events

    Property

    Description

    callId

    Visa Checkout transaction ID, which represents the cancelled payment.

     

    Example: "callId":"..."

    Since 2.0

     

     

    Response to Error Events

    Property

    Description

    status

    HTTPS response status.

     

    Format: Numeric

    Since 2.0

    code

    Internal subcode.

     

    Format: Numeric

    Since 2.0

    severity

    Severity of the error.

     

    Format: It is one of the following values:

    • ERROR

    • WARNING

    Since 2.0

    message

    Description of the error.

     

    Format: Alphanumeric

    Since 2.0

     

    Example

    {

    "responseStatus" : { "status" : 404,

    "code" : "1010",

    "severity" : "ERROR",

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

    }}

     

    Optimizing the Checkout Flow for Mobile Browsers

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

    <html>

    <head>

    ...

    <meta name="viewport"

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

    user-scalable=no" />

    ...

    </head>

     

    Complete Web Page HTML Example

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

     

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

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

     

    <html>

    <head>

    <script type="text/javascript">

    function onVisaCheckoutReady() {

    V.init({

    apikey: "...",

    sourceId: "Merchant Defined Source ID",

    settings: {

    locale: "en_US",

    countryCode: "US",

    displayName: "...Corp",

    logoUrl: "www.Some_Image_URL.gif",

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

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

    shipping: {

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

    collectShipping: "true"

    },

    payment: {

    cardBrands: [

    "VISA",

    "MASTERCARD"],

    acceptCanadianVisaDebit: "true"

    },

    review: {

    message: "Merchant defined message",

    buttonAction: "Continue"

    },

    dataLevel: "SUMMARY"

    },

    paymentRequest: {

    merchantRequestId: "Merchant defined request ID",

    currencyCode: "USD",

    subtotal: "10.00",

    shippingHandling: "2.00",

    tax: "2.00",

    discount: "1.00",

    giftWrap: "2.00",

    misc: "1.00",

    total: "16.00",

    description: "Megacorp Product",

    orderId: "Merchant defined order ID",

    promoCode: "Merchant defined promo code",

    customData: {

    "nvPair": [

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

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

    ]

    }

    }

    }

    );

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

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

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

    }

    </script>

    </head>

    <body>

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

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

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

    <script type="text/javascript"

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

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

    </script>

    </body>

    </html>

     

    Clickjacking Prevention

    Clickjacking Prevention Steps

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

     

    Checking for Hidden Layers

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

     

    <head>

    ...

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

    <script type=”text/javascript”>

    if (self === top) {

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

    antiClickjack.parentNode.removeChild(antiClickjack);

    } else {

    top.location = self.location;

    }

    </script>

    ...

    </head>

     

    Using the X-Options Header

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

     

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

     

    Testing Your Clickjacking Prevention Implementation

     

    To test your implementation of anti-clickjacking measures:

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

     

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

     

    <html>

    <body>

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

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

    </iframe>

    </body>

    </html>

     

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

     

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

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

     

    Example Server-Side Clickjacking Prevention Implementation

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

     

    Java Servlet

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

     

    package com.your_package.filters;

    import java.io.IOException;

    import javax.servlet.Filter;

    import javax.servlet.FilterChain;

    import javax.servlet.FilterConfig;

    import javax.servlet.ServletException;

    import javax.servlet.ServletRequest;

    import javax.servlet.ServletResponse;

    import javax.servlet.http.HttpServletResponse;

    public class ClickjackFilter implements Filter

    {

    private String mode = “DENY”;

    public void doFilter(ServletRequest request, ServletResponse response,

    FilterChain chain) throws IOException, ServletException {

    HttpServletResponse res = (HttpServletResponse)response;

    chain.doFilter(request, response);

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

    }

    public void destroy() {

    }

    public void init(FilterConfig filterConfig) {

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

    if ( configMode != null ) {

    mode = configMode;

    }

    }

    }

     

    List of supported Visa Checkout Transaction Types

    • authorization
    • capture
    • refund
    • void

     

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

     

    Authorization Transaction

    Notes:

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

     

    Request

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

     

    Response

    {

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

    "merchant_address": "3393 Peachtree Road NE",

    "bank_message": "Approved",

    "partial_redemption": 0,

    "transaction_approved": 1,

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

    "bank_resp_code": "100",

    "address": {

    "zip": "90210",

    "country_code": "US",

    "address1": "21 Jump Street",

    "city": "Beverley Hills",

    "state": "CA",

    "phone_number": "2122524000"

    },

    "currency_code": "CAD",

    "avs": "2",

    "transaction_error": 0,

    "exact_resp_code": "00",

    "exact_message": "Transaction Normal",

    "client_ip": "127.0.0.1",

    "transaction_type": "01",

    "merchant_country": "United States",

    "gateway_id": "AD0160-01",

    "cc_expiry": "1016",

    "sequence_no": "000005",

    "merchant_postal": "30342",

    "visa_checkout": {

    "call_id": "5467428919436032412"

    },

    "cvd_presence_ind": 0,

    "merchant_city": "Atlanta",

    "cardholder_name": "Timothy Duncan",

    "credit_card_type": "Visa",

    "retrieval_ref_no": "7526387",

    "transaction_tag": 5273,

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

    "cvv2": "I",

    "merchant_province": "Georgia",

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

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

    "authorization_num": "ET187971",

    "amount": 1036.26

    }

     

    Capture Transaction – Capture of a previous Authorization

    Notes

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

     

    Request

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

     

    Response

    {

    "merchant_postal": "30342",

    "transaction_type": "32",

    "amount": 1036.26,

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

    "transaction_tag": 5274,

    "retrieval_ref_no": "2655088",

    "bank_message": "Approved",

    "exact_resp_code": "00",

    "cvv2": "I",

    "merchant_address": "3393 Peachtree Road NE",

    "currency_code": "CAD",

    "visa_checkout": {

    "call_id": "5467428919436032412"

    },

    "merchant_city": "Atlanta",

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

    "partial_redemption": 0,

    "transaction_approved": 1,

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

    "merchant_country": "United States",

    "authorization_num": "ET191879",

    "gateway_id": "AD0160-01",

    "bank_resp_code": "100",

    "cardholder_name": "Timothy Duncan",

    "credit_card_type": "Visa",

    "cc_expiry": "1016",

    "cvd_presence_ind": 0,

    "sequence_no": "000005",

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

    "merchant_province": "Georgia",

    "transaction_error": 0,

    "exact_message": "Transaction Normal",

    "client_ip": "127.0.0.1"

    }

     

    Refund Transaction – Refund of a previous Capture Transaction

    Notes

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

     

    Request

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

     

    Response

    {

    "merchant_postal": "30342",

    "transaction_type": "34",

    "amount": 500.34,

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

    "transaction_tag": 5275,

    "retrieval_ref_no": "7769505",

    "bank_message": "Approved",

    "exact_resp_code": "00",

    "cvv2": "I",

    "merchant_address": "3393 Peachtree Road NE",

    "currency_code": "CAD",

    "visa_checkout": {

    "call_id": "5467428919436032412"

    },

    "merchant_city": "Atlanta",

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

    "partial_redemption": 0,

    "transaction_approved": 1,

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

    "merchant_country": "United States",

    "authorization_num": "ET165885",

    "gateway_id": "AD0160-01",

    "bank_resp_code": "100",

    "cardholder_name": "Timothy Duncan",

    "credit_card_type": "Visa",

    "cc_expiry": "1016",

    "cvd_presence_ind": 0,

    "sequence_no": "000006",

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

    "merchant_province": "Georgia",

    "transaction_error": 0,

    "exact_message": "Transaction Normal",

    "client_ip": "127.0.0.1"

    }

     

    Void Transaction – Void of a previous Refund Transaction

    Notes

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

     

    Request

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

     

    Response

    {

    "merchant_postal": "30342",

    "transaction_type": "33",

    "amount": 500.34,

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

    "transaction_tag": 5276,

    "retrieval_ref_no": "0139961",

    "bank_message": "Approved",

    "exact_resp_code": "00",

    "cvv2": "I",

    "merchant_address": "3393 Peachtree Road NE",

    "currency_code": "CAD",

    "visa_checkout": {

    "call_id": "5467428919436032412"

    },

    "merchant_city": "Atlanta",

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

    "partial_redemption": 0,

    "transaction_approved": 1,

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

    "merchant_country": "United States",

    "authorization_num": "ET149705",

    "gateway_id": "AD0160-01",

    "bank_resp_code": "100",

    "cardholder_name": "Timothy Duncan",

    "credit_card_type": "Visa",

    "cc_expiry": "1016",

    "cvd_presence_ind": 0,

    "sequence_no": "000006",

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

    "merchant_province": "Georgia",

    "transaction_error": 0,

    "exact_message": "Transaction Normal",

    "client_ip": "127.0.0.1"

    }

     

     

    3.7 Debit Bill Pay

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

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

     

    Debit Bill Pay Transaction Sample:

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

    Please see  format samples below.

     

    Request Sample (JSON):

     "Transaction": {

       "ExactID": "XXXXXXXX",

       "Password": "XXXXXXXX",

       "Card_Number": "XXXXXXXXXXXXX",

       "Transaction_Type": "00",

       "DollarAmount": "50",

       "Expiry_Date": "1017",

       "CardHoldersName": "Happy Customer",

       "CardType": "Debit Bill Pay",

       "Currency_Code": "USD"

     }

     

    Request Sample (XML):

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

    <Transaction>

    <ExactID>XXXXXXXX</ExactID>

    <Password>XXXXXXXXX</Password>

    <Card_Number>XXXXXXXXXXXXXXXX</Card_Number>

    <Transaction_Type>00</Transaction_Type>

    <DollarAmount>50</DollarAmount>

    <Expiry_Date>1018</Expiry_Date>

    <CardHoldersName>Happy Customer</CardHoldersName>

    <CardType>Debit Bill Pay</CardType>

    <Currency_Code>USD</Currency_Code>

    </Transaction>

      

    Response Sample (JSON):

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

     

     

    Response Sample (XML):

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

    <TransactionResult>

    <ExactID>XXXXXXXXX</ExactID>

    <Password/>

    <Transaction_Type>00</Transaction_Type>

    <DollarAmount>50.0</DollarAmount>

    <SurchargeAmount/>

    <Card_Number>XXXXXXXXXXXXXXXXXX</Card_Number>

    <Transaction_Tag>4883300</Transaction_Tag>

    <Track1/>

    <Track2/>

    <PAN/>

    <Authorization_Num>332932</Authorization_Num>

    <Expiry_Date>0918</Expiry_Date>

    <CardHoldersName>Happy Customer</CardHoldersName>

    <VerificationStr1/>

    <VerificationStr2/>

    <CVD_Presence_Ind>0</CVD_Presence_Ind>

    <ZipCode/>

    <Tax1Amount/>

    <Tax1Number/>

    <Tax2Amount/>

    <Tax2Number/>

    <Secure_AuthRequired/>

    <Secure_AuthResult/>

    <Ecommerce_Flag/>

    <XID/>

    <CAVV/>

    <CAVV_Algorithm/>

    <Reference_No/>

    <Customer_Ref/>

    <Reference_3/>

    <Language/>

    <Client_IP/>

    <Client_Email/>

    <User_Name/>

    <Transaction_Error>false</Transaction_Error>

    <Transaction_Approved>true</Transaction_Approved>

    <EXact_Resp_Code>00</EXact_Resp_Code>

    <EXact_Message>Transaction Normal</EXact_Message>

    <Bank_Resp_Code>100</Bank_Resp_Code>

    <Bank_Message>Approved</Bank_Message>

    <Bank_Resp_Code_2/>

    <SequenceNo>0200862</SequenceNo>

    <AVS/>

    <CVV2/>

    <Retrieval_Ref_No>151014</Retrieval_Ref_No>

    <CAVV_Response/>

    <Currency>USD</Currency>

    <AmountRequested>0.0</AmountRequested>

    <PartialRedemption>false</PartialRedemption>

    <MerchantName>XXXXXXXXXXXX</MerchantName>

    <MerchantAddress/>

    <MerchantCity/>

    <MerchantProvince>XXXXXXX</MerchantProvince>

    <MerchantCountry>XXXXXXXX</MerchantCountry>

    <MerchantPostal/>

    <MerchantURL/>

    <TransarmorToken/>

    <CardType>Debit Bill Pay</CardType>

    <CurrentBalance/>

    <PreviousBalance/>

    <EAN/>

    <CardCost/>

    <VirtualCard>false</VirtualCard>

    <CTR>

     

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

     

     

    3.8 Special Payment Transactions

    The API v21 and higher supports the Special Payment feature. 

     

    Special Payment Transaction Sample:

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

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

    Field name Data Type Request Values  Response Values

    special_payment (JSON) 

    SpecialPayment (XML)

    (API v21 and higher)

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

     

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

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

     

    API Request sample (JSON):

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

     

    API Response sample (JSON):

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

     

    3.9 Wallet Provider ID

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

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

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

     

    Field name Data Type Request Values  Response Values

    wallet_provider_id (JSON) 

    WalletProviderID  (XML)

    (API v22 and higher )

     String

    (optional) 

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

     

    API Request example (JSON):

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

     

    API Response example (JSON):

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

     

    3.10 Payment Facilitator (PFac)

    Preparation:

     

    API Fields for Global Payment Facilitator Transactions (Multi MID PFac)


    There are no additional API fields needed for Global Payment Facilitator. 

    Sample Global PFac Transaction Request (JSON)

    {

    "mid":"xxxxxxxxxxxx",

    "division_id":"xxxxxx",

    "transaction_type":"00",

    "cc_number":"xxxxxxxxxxxx0026",

    "correlation_id":"Unique_Correlation_ID_1",

    "amount":"10.00",

    "cc_expiry":"1225",

    "cardholder_name":"John Doe",

    "address": {

      "address1":"12115 LACKLAND",

      "address2":"",

      "city":"St Louis",

      "state":"MO",

      "zip":"63146",

      "country_code":"US",

      "phone_number":"1234567890",

      "phone_type":"H"

    }

     

    }

     

    Sample Global PFac Transaction Response (JSON)

     

    {"transaction_error":0,"transaction_approved":1,"exact_resp_code":"00","exact_message":"Transaction Normal","bank_resp_code":"100","bank_message":"Approved","sequence_no":"0836600","retrieval_ref_no":"170324","merchant_name":"Payment FACILITATOR1","merchant_address":"ADDRESS","merchant_city":"CITY","merchant_province":"New York","merchant_country":"United States","merchant_postal":"90210","merchant_url":"WWW.E-XACT.COM","ctr":"========== TRANSACTION RECORD ==========\nPayment FACILITATOR1\nADDRESS\nCITY, NY 90210\nUnited States\nWWW.E-XACT.COM\n\nTYPE: Purchase\n\nACCT: Visa                   $ 10.00 USD\n\nCARDHOLDER NAME : John Doe\nCARD NUMBER     : ############0026\nDATE/TIME       : 24 Mar 17 16:12:40\nREFERENCE #     : 001 0836600 M\nAUTHOR. #       : 150988\nTRANS. REF.     : \n\n    Approved - Thank You 100\n\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================","gateway_id":"xxxxxx-xx","transaction_type":"00","amount":10.0,"cc_number":"############0026","transaction_tag":xxxxxxx,"authorization_num":"xxxxxx","cc_expiry":"1225","cardholder_name":"John Doe","cvd_presence_ind":0,"currency_code":"USD","partial_redemption":0,"credit_card_type":"Visa","correlation_id":"Unique_Correlation_ID_1","soft_descriptor":{"mvv_maid":"1234abcd"},"address":{"address1":"12115 LACKLAND","city":"St Louis","state":"MO","zip":"63146","country_code":"US","phone_number":"1234567890","phone_type":"H"}}




    API Fields for Legacy Payment Facilitator Transactions (Single MID PFac)

     

    Field Name

    Length

    Data Type

    Description

    soft_descriptor

    Not applicable

    Not applicable

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

    dba_name

    Maximum length of 22.



    Alphanumeric

    dba_name must be formatted as shown--the prefix indicates the Payment Facilitator (‘XYZ’) and the suffix indicates the Submerchant (‘ASMALLCO’):

    Example:

    XYZ*ASMALLCO


    Prefices and suffices must adhere to this format:

    3 chars * 18 chars (max)

    7 chars * 14 chars (max)

    12 chars * 9 chars (max)

    pfac_name

    Maximum length of 50. Note that pfac_name should NOT be submitted for AMEX transactions.

    Alphanumeric

    Payment Facilitator name, as registered with the appropriate Card Brand.

    pfac_submerchant_id

    Minimum length of 10.
    For AMEX, it must be between 10-20 characters.
    For MasterCard, it must be between 15-20 characters.

    Alphanumeric

     

    mvv_maid

    10 digits for VISA transactions; 6 digits for all non-VISA transactions

    Alphanumeric

     

    amex_merchant_phone

    Length of 24

    Alphanumeric

    Sub-merchant phone. For AMEX transactions only.

    amex_merchant_email

    Length of 40

    Alphanumeric

    Sub-merchant email. For AMEX transactions only.




    Sample Legacy PFac Transaction JSON Request

     

    {

    "gateway_id":"xxxxxx-xx",

    "password":"xxxxxxxx",

    "transaction_type":"00",

    "Cc_number":"xxxxxxxxxxxx0026",

    "amount":"10.00",

    "cc_expiry":"1225",

    "cardholder_name":"John Doe",

    "address": {

      "address1":"12115 LACKLAND",

      "address2":"",

      "city":"St Louis",

      "state":"MO",

      "zip":"63146",

      "country_code":"US",

      "phone_number":"1234567890",

      "phone_type":"H"

    },

    "soft_descriptor":{

      "dba_name":"MSC*EXACTSOFT",

      "pfac_name":"microexact",

      "street":"12115 LACKLAND",

      "city":"855-448-3493",

      "region":"MO",

      "postal_code":"63146",

      "country_code":"US",

      "mid":"",

      "mcc":"456",

      "merchant_contact_info":"contactus@welovesoftware.com",

      "pfac_submerchant_id":"abcdefg1234567890",

      "mvv_maid":"0123456789"

       }

    }

     

    Sample Legacy PFac Transaction JSON Response

    {"transaction_error":0,"transaction_approved":1,"exact_resp_code":"00","exact_message":"Transaction Normal","bank_resp_code":"100","bank_message":"Approved","sequence_no":"0056286","avs":"Y","retrieval_ref_no":"170324","merchant_name":"PFAC Terminal Settlement Name","merchant_province":"Alabama","merchant_country":"United States","ctr":"========== TRANSACTION RECORD ==========\nPFAC Terminal Settlement Name\n\n, AL\nUnited States\n\n\nTYPE: Purchase\n\nACCT: Visa                   $ 10.60 USD\n\nCARDHOLDER NAME : John Doe\nCARD NUMBER     : ############0026\nDATE/TIME       : 24 Mar 17 11:45:41\nREFERENCE #     : 001 0056286 M\nAUTHOR. #       : 402570\nTRANS. REF.     : \n\n    Approved - Thank You 100\n\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================","gateway_id":"xxxxxx-xx","transaction_type":"00","amount":10.6,"cc_number":"############0026","transaction_tag":xxxxxxx,"authorization_num":"xxxxxx","cc_expiry":"1225","cardholder_name":"John Doe","cvd_presence_ind":0,"cavv_algorithm":"microexact","currency_code":"USD","partial_redemption":0,"credit_card_type":"Visa","soft_descriptor":{"dba_name":"MSC*EXACTSOFT","street":"12115 LACKLAND","city":"855-448-3493","region":"MO","postal_code":"63146","country_code":"US","mcc":"456","merchant_contact_info":"contactus@welovesoftware.com","mvv_maid":"0123456789","pfac_submerchant_id":"abcdefg1234567890","pfac_name":"microexact"},"address":{"address1":"12115 LACKLAND","city":"St Louis","state":"MO","zip":"63146","country_code":"US","phone_number":"1234567890","phone_type":"H"}}

     

    3.11 Masterpass

    API transactions for MasterPass are supported by API v24 and above.
    Please ensure to read section 3.9 Wallet Provider ID. If a digital wallet was used during a transaction, then the Wallet Provider ID must be specified.



    Field Name

    Data Type

    Description

    master_pass

    Not applicable

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

    transaction_id

    Numeric

    Transaction identifier

    wallet_id

    Numeric

    Valid Values:

    101 = Masterpass Remote

    102 = Masterpass Remote NFC

    (Other values will be issued by Mastercard in the future).


     

    indicator

    String

    Valid Values:

    N - Non-SecureCode

    U - UCAF

    S - Static AAV

    A - Mastercard risk-based-decisioning

    I - Issuer risk-based-decisioning

    M - Merchant risk-based-decisioning

    Space - not applicable

     

    Sample Masterpass Transaction JSON Request

    {
    "gateway_id": "P08976-86",
    "password": "some_password",
    "cc_number": "4012000033330026",
    "transaction_type": "00",
    "cardholder_name": "MP test",
    "cc_expiry": "1023",
    "amount": "10.00",
    "reference_no": "R1111",
    "customer_ref": "CR444",
    "email_address": "test@masterpass.com",
    "wallet_provider_id": "3",
    "master_pass": {
      "transaction_id": "3752301070040561792",
      "wallet_id": "101",
      "indicator": "N"
      }
    }
    

    Sample Masterpass Transaction JSON Response

    {

    "transaction_error":0,

    "transaction_approved":1,

    "exact_resp_code":"00",

    "exact_message":"Transaction Normal",

    "bank_resp_code":"100",

    "bank_message":"Approved",

    "bank_resp_code_2":"01",

    "sequence_no":"0612189",

    "retrieval_ref_no":"170314",

    "merchant_name":"MP test",

    "merchant_address":"56 Quete St",

    "merchant_city":"Vancouver",

    "merchant_province":"British Columbia",

    "merchant_country":"Canada",

    "merchant_postal":"V7L 4M8",

    "ctr":"========== TRANSACTION RECORD ==========\nMP test\n56 Quete St\nVancouver, BC V7L 4M8\nCanada\n\n\nTYPE: Purchase\n\nACCT: Visa $ 10.00 USD\n\nCARDHOLDER NAME : MP test\nCARD NUMBER : ############0026\nDATE/TIME : 14 Mar 17 12:48:33\nREFERENCE # : 005 0612189 M\nAUTHOR. # : ET4835\nTRANS. REF. : R1111\n\n Approved - Thank You 100\n\n\nPlease retain this copy for your records.\n\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================",

    "gateway_id":"P08976-86",

    "transaction_type":"00",

    "amount":10.0,

    "cc_number":"############0026",

    "transaction_tag":2520646,

    "authorization_num":"ET4835",

    "cc_expiry":"1023",

    "cardholder_name":"MP test",

    "cvd_presence_ind":0,

    "reference_no":"R1111",

    "customer_ref":"CR444",

    "currency_code":"USD",

    "partial_redemption":0,

    "credit_card_type":"Visa",

    "master_pass":{

    "transaction_id":"3752301070040561792",

    "wallet_id":"101",

    "indicator":"N"

    }

    } 

     

    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
    • 03 = Forced Post
    • 04 = Refund
    • 05 = Pre-Authorization Only
    • 07 = PayPal Order
    • 13 = Void
    • 32 = Tagged Pre-Authorization Completion
    • 33 = Tagged Void
    • 34 = Tagged Refund
    • 83 = CashOut (ValueLink, v9 or higher end point only)
    • 85 = Activation (ValueLink, v9 or higher end point only)
    • 86 = Balance Inquiry (ValueLink, v9 or higher end point only)
    • 88 = Reload (ValueLink, v9 or higher end point only)
    • 89 = Deactivation (ValueLink, v9 or higher end point only)

     

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

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

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

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

    Required Character Format is ASCII.

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

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

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

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

    Required Character Format is ASCII.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Required Character Format is ASCII.

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

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

    Required Character Format is ASCII.

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

    user_name (JSON format)

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

    Currency

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

    PartialRedemption

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

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

    CAVV

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

    XID

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

    Ecommerce_Flag

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

    TransarmorToken

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

    transarmor_token (JSON format)

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

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

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

    CardType

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

    credit_card_type (JSON format)

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

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

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

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

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

    VirtualCard

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

    CardCost

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

    FraudSuspected

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

    CheckNumber

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

    The check number being used to complete payment.

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

    CheckType

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

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

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

    BankAccountNumber

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

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

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

    BankRoutingNumber

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

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

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

    CustomerName

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

    The name of the customer making the payment.

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

    CustomerIDType

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

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

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

    CustomerID

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

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

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

    TPPID

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

    tpp_id (JSON format)

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

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

    This property is only applicable to the v14 endpoint.

    SplitTenderID

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

    split_tender_id (JSON format)

    Split Tender ID.

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

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

    SplitShipmentNumber

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

    split_shipment_number(JSON format)

     

    SplitShipmentNumber

    String ("xx/yy")

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

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

    <SplitShipmentNumber>02/05</SplitShipmentNumber>

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

     

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

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

    4.1 Address Properties

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

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

    Property Length Format Required/Optional Description

    Address

    address (JSON format)

          Parent of the properties listed below.

    Address1

    address1 (JSON format)

    30 String Optional  

    Address2

    address2 (JSON format)

    28 String Optional  

    City

    city (JSON format)

    20 String Optional  

    State

    state (JSON format)

    2 String Optional  

    Zip

    zip (JSON format)

    10 String Optional  

    CountryCode

    country_code (JSON format)

    2 String Optional  

    PhoneNumber

    phone_number (JSON format)

    14 String Optional Non digits will be removed before processing

    PhoneType

    phone_type (JSON format)

    1 String Optional

    Only the following values are accepted:

    H = Home

    W = Work

    D = Day

    N = Night

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

     

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

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

     

    The same example, this time in JSON format:

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

     

    4.2 Level 2 Properties

     

    Tax1Amount

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

    tax1_amount (JSON format)

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

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

    Tax1Number

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

    tax1_number (JSON format)

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

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

    Tax2Amount

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

    tax2_amount (JSON format)

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

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

    Tax2Number

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

    tax2_number (JSON format)

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

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

    Customer_Ref

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

    customer_ref (JSON format)

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

    Required Character Format is ASCII.

     

    4.3 Level 3 Properties

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

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

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

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

    For the following table, Format abbreviations are:

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

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

    Property

    Length

    Format

    Required/ Optional

    Description

    Level3

    level3 (JSON format)

       

    Required

    Parent of the properties listed below.

    TaxAmount

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

    tax_amount (JSON format)

    12

    N

    Required

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

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

    Value should be >= $0.00

    TaxRate

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

    tax_rate (JSON format)

    4

    N

    Optional

    Tax rate applied to the item

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

    AltTaxAmount

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

    alt_tax_amount (JSON format)

    9

    N

    Optional

    Total amount of alternate tax associated with this transaction.

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

     

    AltTaxId

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

    alt_tax_id (JSON format)

    14

    A

    Optional

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

    DiscountAmount

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

    discount_amount (JSON format)

    12

    N

    Required

    Amount of discount applied to the total transaction.

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

    DutyAmount

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

    duty_amount (JSON format)

    12

    N

    Required

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

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

    FreightAmount

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

    freight_amount (JSON format)

    12

    N

    Required

    Total freight or shipping and handling charges.

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

    ShipFromZip

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

    ship_from_zip (JSON format)

    10

    A

    Optional

     

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

    ShipToAddress

    ship_to_address (JSON format)

       

    Optional

    Parent of the properties listed below.

    Address1

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

    address_1 (JSON format)

    28

    A

    Optional

    The Street Address of the “ship to” location.

    Required Character Format is UPPER.

    City

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

    city (JSON format)

    20

    A

    Optional

    The City of the “ship to” location.

    Required Character Format is UPPER.

    State

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

    state (JSON format)

    2

    A

    Optional

    The State of the “ship to” location.

    Required Character Format is UPPER.

    Zip

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

    zip (JSON format)

    2

    A

    Optional

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

    Country

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

    country (JSON format)

    2

    A

    Optional

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

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

    CustomerNumber

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

    customer_number (JSON format)

    20

    A

    Optional

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

    Email

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

    email (JSON format)

    50

    A

    Optional

    The Accountholder’s email address associated with the transaction.

    Name

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

    name (JSON format)

    28

    A

    Optional

    The Accountholder’s name associated with the transaction.

    asterisk should precede last name ex: *LAST

    Phone

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

    phone (JSON format)

    14

    A

    Optional

    The Accountholder’s phone number associated with the transaction.

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

    LineItem

    line_items (JSON format)

       

    Required

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

    CommodityCode

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

    commodity_code (JSON format)

    12

    N

    Required

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

     

    Description

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

    description (JSON format)

    26

    N

    Required

    Item description.

    Required Character Format is ASCII.

     

    DiscountAmount

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

    discount_amount (JSON format)

    12

    N

    Required

    The discounted amount for the line item.

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

     

    DiscountIndicator

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

    discount_indicator (JSON format)

     

    B

    Required

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

    1 – Discounted

    0 – Not Discounted

     

    GrossNetIndicator

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

    gross_net_indicator (JSON format)

     

    B

    Required

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

    1 – Tax included

    0 – Tax Excluded

     

    LineItemTotal

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

    line_item_total (JSON format)

    12

    N

    Required

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

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

     

    ProductCode

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

    product_code (JSON format)

    12

    A

    Required

    The UPC product code for the line item.

    Required Character Format is ASCII.

     

    Quantity

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

    quantity (JSON format)

    5

    N

    Required

     

    Number of units of the item purchased

     

     

    TaxAmount

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

    tax_amount (JSON format)

    12

    N

    Optional

    The amount of tax charged on the line item.

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

     

    TaxRate

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

    tax_rate (JSON format)

    4

    N

    Optional

    The rate of tax charged on the line item.

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

    TaxType

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

    tax_type (JSON format)

    4

    A

    Optional

    Type of tax being applied.

    UnitCost

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

    unit_cost (JSON format)

    12

    N

    Required

    The per unit cost of the line item.

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

    UnitOfMeasure

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

    unit_of_measure (JSON format)

    12

    A

    Required

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

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

     

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

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

    JSON Level 3 Example:

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

    4.4 PayPal Properties

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

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

    Property Description

    PaypalTransactionDetails

    paypal_transaction_details (JSON format)

    Parent of the properties listed below.

    PayerID

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

    GrossAmountCurrencyID

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

    Sucess

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

    Authorization

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

    Message

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

    CorrelationID

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

    Timestamp

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

    Integrating PayPal's Express Checkout API

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

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

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

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

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

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

    Payeezy Gateway JSON Data Content:

    {

    "gateway_id":"A00123-01",

    "amount":201.50,

    "transaction_type":"07",

    "credit_card_type":"Paypal",

    "cardholder_name":" ARTHUR DIGBY SELLERS",

    "password":"secret",

    "paypal_transaction_details": {

    "correlation_id":"11d8cac11e8",

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

    "authorization":"O-123456789ABCDEFGH",

    "payer_id":"ADUMMYPAYERID",

    "gross_amount_currency_id":"USD",

    "success":true,

    "message":"Success"}

    }

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

     

    4.5 Soft Descriptor Properties

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

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

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

     

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

    DBAName

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


    Required Character Format is ASCII.

    Street

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

    Business address

    Required Character Format is ASCII.

    City

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


    Required Character Format is ASCII.

    Region

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


    Required Character Format is ASCII.

    PostalCode

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

    CountryCode

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

    MID

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

    MCC

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

    MerchantContactInfo

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


    Required Character Format is ASCII.

     

    Soft Descriptor JSON Example

     

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

     

    4.6 Telecheck Properties

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

    Property Description

    CheckNumber

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

    CheckType

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

    BankAccountNumber

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

    BankRoutingNumber

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

    CustomerName

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

    CustomerIDType

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

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

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

    CustomerID

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

    ReleaseType

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

    release_type (JSON format)

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

    GiftCardAmount

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

    gift_card_amount (JSON format)

    Gift card amount associated with the transaction.

    DateOfBirth

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

    date_of_birth (JSON format)

    Customer's date of birth in MMDDYYYY format.

    VIP

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

    vip (JSON format)

    VIP status of the transction.

    RegistrationNo

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

    registration_no (JSON format)

    Registration number associated with the transaction.

    RegistrationDate

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

    registration_date (JSON format)

    Registration date in MMDDYYYY format.

    ClerkID

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

    clerk_id (JSON format)

    Clerk ID number associated with the transaction.

    DeviceID

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

    device_id (JSON format)

    Device ID associated with the transaction.

    MICR

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

    micr (JSON format)

    MICR associated with the transaction.

     

    4.7 Fees

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

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

     

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

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

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

     

    Property

    Description

    FeeAmount

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

     

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

     

    4.8 DCC Properties

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

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

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

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

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

    Property

    Description

    OptedIn

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

    RateResponseSignature

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

     

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

    SOAP / XML Example:

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

     

    JSON Example:

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

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

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

    4.9 DP Properties

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

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

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

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

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

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

     

    Property

    Description

    OptedIn

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

    RateResponseSignature

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

     

    SOAP / XML Example:

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

     

    JSON Example:

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

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

     

    4.10 Foreign Currency Details Properties

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

    Property

    Description

    DCCIndicator

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

    ForeignAmount

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

    ForeignCurrencyCode

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

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

    ExchangeRate

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

    MarginRate

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

    RateSource

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

     

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

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

    Transaction Type
    Code
    Purchase 00
    Pre Authorization 01

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

  • Transaction Type

    Code

    Refund

    04

    Tagged Completion

    32

    Tagged Void

    33

    Tagged Refund

    34

  •  

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

    5 Response Properties

  • Upcoming Maintenance for the Transaction_Tag Value upgrade on 08/09/2017 during regular maintenance window.

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

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

    AmexFraud

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

    Support (AF) Amex Fraud Mitigation Reply Format Indicators

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

    Indicator Codes:

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

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

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

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

    ForeignCurrencyDetails

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

       

     

    6 SOAP Message Format

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

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

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

    6.1 Request Message Format

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

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

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

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

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

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

    Example 5.1 SOAP Request Message with a Referenced Transaction Struct

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

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

    Example 5.2 SOAP Request Message with an Embedded Transaction Struct

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

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

    6.2 Response Message Format

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

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

    Example 5.3 SOAP Response Message with a Referenced TransactionResult Struct

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

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

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

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

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

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

    7 A Few Examples Using cURL

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

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

    7.1 Example 1. Pre-Authorization

    This request illustrates the following:

    • using the SOAP style Payeezy Gateway Web Service API
    • passing authentication credentials as HTTP Basic Authentication username:password values
    • pre-authorizing the given credit card, which allows for capturing funds at a later time via the Completion transaction
    curl -u 'ExactID:Password' \
    
    -H 'SOAPAction: http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/SendAndCommit' \
    -H 'Content-Type: text/xml' \
    -d '<?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/" xmlns:types="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/encodedTypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <q1:SendAndCommit xmlns:q1="http://api.globalgatewaye4.firstdata.com/vplug-in/transaction/rpc-enc/Request">
    <SendAndCommitSource href="#id1" />
    </q1:SendAndCommit>
    <types:Transaction id="id1" xsi:type="types:Transaction">
    <Transaction_Type xsi:type="xsd:string">01</Transaction_Type>
    <DollarAmount xsi:type="xsd:string">15.75</DollarAmount>
    <Card_Number xsi:type="xsd:string">4111111111111111</Card_Number>
    <Expiry_Date xsi:type="xsd:string">1015</Expiry_Date>
    <CardHoldersName xsi:type="xsd:string">Walter Sobchak</CardHoldersName>
    </types:Transaction>
    </soap:Body>
    </soap:Envelope>' \
    https://api.globalgatewaye4.firstdata.com/transaction

    The resulting request headers and response:

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

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

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

    TYPE: Pre-Authorization

    ACCT: Visa $ 15.75 USD

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

    Approved - Thank You 000


    Please retain this copy for your records.

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

    7.2 Example 2. Tagged Pre-Authorization Completion

    This request illustrates the following:

    • using the REST Payeezy Gateway Web Service API with XML message format
    • passing authentication credentials in the message as ExactID and Password properties
    • completing the Pre-Authorization transaction from Example 1 using the response properties from that transaction
    curl -H 'Content-Type: application/xml; charset=UTF-8' \
    
    -H 'Accept: application/xml' \
    -d '<?xml version="1.0" encoding="UTF-8"?>
    <Transaction>
    <ExactID>ExactID</ExactID>
    <Password>Password</Password>
    <Transaction_Type>32</Transaction_Type>
    <Transaction_Tag>901975484</Transaction_Tag>
    <Authorization_Num>ET4653</Authorization_Num>
    <DollarAmount>15.75</DollarAmount>
    </Transaction>' \
    https://api.globalgatewaye4.firstdata.com/transaction

    The resulting request headers and response:

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

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

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

    TYPE: Pre-Auth Completion

    ACCT: Visa $ 15.75 CAD

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

    Approved - Thank You 000


    Please retain this copy for your records.

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

    7.3 Example 3. Tagged Refund

    This request illustrates the following:

    • using the REST Payeezy Gateway Web Service API with JSON message format
    • passing authentication credentials as HTTP Basic Authentication username:password values
    • refunding the Tagged Pre-Authorization Completion transaction from Example 2 using the response properties from that transaction
    curl -u 'ExactID:Password' \
    
    -H 'Content-Type: application/json; charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{
    "transaction_type":"34",
    "transaction_tag":"902006933",
    "authorization_num":"ET4653",
    "amount":"15.75"
    }' \
    https://api.globalgatewaye4.firstdata.com/transaction

    The resulting request headers and response:

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

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

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

    8 Exception Handling

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

    8.1 SOAP Exception

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

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

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

    Client and Server are the most common values returned.

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

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

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

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

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

    8.2 SOAP Exception Scenarios

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

    Example 6.1 SOAP Exception for a Malformed Incoming SOAP Message

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

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

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

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

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

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

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

    8.3 Response - Error Properties

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

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

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

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

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

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

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

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

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

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

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

    9 API HMAC Security (V12+)

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

     

    Appendix 1. More About Service URLs

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

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

    Below is a comprehensive list of the service URLs:

     

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

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

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

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

    Removed Properties: LogonMessage, ErrorNumber and ErrorDescription

    V10

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

    Other changes: PayPal Order Support

    V11

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

    V12

    Added Properties: FraudSuspected

    Other changes: HMAC authentication support

    V13

    Added TeleCheck support

    V14

    Replaced Property:

    VerificationStr1 replaced with Address element

    VerificationStr2 replaced with CVDCode

    Added Property: SplitTenderID, TPPID

     

    V15

    Added Property: SplitShipmentNumber

    V16

    Added support for Amex Fraud Mitigation Reply Format Indicators

     

    V17

    Added support for DCC and DP

     

    V18  Added support for Fees
    V19 Added support for Visa Checkout (VCO)
    V20 This version was skipped
    V21 Added support for Special Payments
    V22 Added support for wallet_provider_id
    V23 Added support for Payment Facilitator
    V24 Added support for MasterPass


Powered by Zendesk