• 1 Intended Audience
• 2 Introduction
• 2.1 Basic Information
• 3 API Transactions
• 3.0.1 Card Verification. CVV/CVC related processing
• 3.1 PayPal
• 3.2 Zero Dollar Pre-Authorizations
• 3.3 Gift Cards
• 3.3a Split Tender
• 3.4 TransArmor
• 3.5 Telecheck
• 3.6 Visa Checkout
• 3.7 Debit Bill Pay
• 3.8 Special Payment
• 3.9 Wallet Provider ID
  
• 3.10 Payment Facilitator
  
• 3.11 Masterpass
  
• 3.12 Timeout Reversal
• 3.13 Stored Credentials (Credentials-on-File)
• 3.14 Visa Non Original Credit Account Funding Transaction (NON-OCT AFT)
• 3.15 3DS version 2
• 3.16 Business Application Indicator (BAI)
• 3.17 Foreign Access Code (FAC)
• 4 Request Properties
• 4.1 Address Properties
• 4.2 Level 2 Properties
• 4.3 Level 3 Properties
• 4.4 PayPal Properties
• 4.5 Soft Descriptor Properties
• 4.6 Fees
• 4.7 DCC Properties
• 4.8 DP Properties
• 4.9 Foreign Currency Details Properties
• 4.10 Fraud Detect
• 5 Response Properties
• 6 SOAP Message Format
• 6.1 Request Message Format
• 6.2 Response Message Format
• 7 A Few Examples Using cURL
• 7.1 Example 1. Pre-Authorization
• 7.2 Example 2. Tagged Pre-Authorization Completion
• 7.3 Example 3. Tagged Refund
• 8 Exception Handling
• 8.1 SOAP Exception
• 8.2 SOAP Exception Scenarios
• 8.3 Response - Error Properties
• 9 API HMAC Security
• Appendix 1. More About Service URLs
• Appendix 2. Endpoints and WSDL URLs
• Appendix 3. API versions and features

1 Intended Audience

This document is intended for Developers who want to understand and implement the First Data Payeezy Gateway 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, Tagged 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 REST and SOAP, 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 latest API version is 31.
The service URLs are:

• Endpoint - https://api.globalgatewaye4.firstdata.com/transaction/v32
• WSDL - https://api.globalgatewaye4.firstdata.com/transaction/v32/wsdl

For previous API versions and the list of suppoted features by API version, please refer to Appendix 3:
https://support.payeezy.com/hc/en-us/articles/206601408#apx3

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 (https://support.payeezy.com/hc/en-us/articles/203731149).

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.

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 Gift Solutions (ValueLink) transactions are handled in their own tables below.

3.0.1 Card Verification. CVV/CVC related processing

CVV-related API request fields

CVV-related API response field

How to enable CVD/CVV2 Processing:
https://support.payeezy.com/hc/en-us/articles/203826399

How to setup a CVV filter and Terminal Type:
https://support.payeezy.com/hc/en-us/articles/204504205

How to simulate Payeezy Gateway responses:
https://support.payeezy.com/hc/en-us/articles/204504185


Please note:

• Payeezy Gateway mirrors back most of the API fields that were sent to it. However, please don't plan for logic that relies on receiving back "cvd_code". Storage of "cvd_code" is against PCI compliance. Hence, Payeezy Gateway won't mirror back "cvd_code".
• Send CVV value only via the "cvd_code" field. Sending CVV values via other fields is prohibited by Payeezy Gateway and storage of CVV values is prohibited by PCI compliance. Payeezy Gateway team will scrap CVV values presented in other API fields; including in reference-related fields. 

API request example (simulating a transaction with a CVV match):
(simulation values for Demo terminals: https://support.payeezy.com/hc/en-us/articles/204504185) 

{
"cc_number": "XXXXXXX", 
"cardholder_name":"John Doe",
"transaction_type": "00",
"cc_expiry": "1122",
"amount": "5.00",
"gateway_id": "XXXXXX",
"password": "XXXXXXXXX", 
"cvd_code":"123",
"cvd_presence_ind":"1"
}

API response example: 

'{"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":"0108422","cvv2":"M","retrieval_ref_no":"200525","merchant_name":"MGZ test API","merchant_address":"3722 Crenshaw Blvd","merchant_city":"Los Angeles","merchant_province":"California","merchant_country":"United States","merchant_postal":"90016","merchant_url":"https://admin.gateway.payeezyqa.com","ctr":"========== TRANSACTION RECORD ==========\\nXXXXXXX \\n3722 Crenshaw Blvd\\nLos Angeles, CA 90016\\nUnited States\\nhttps:/XXXXXXXXX.com\\n\\nTYPE: Purchase\\n\\nACCT: Mastercard              $ 5.00 USD\\n\\nCARDHOLDER NAME : John Doe\\nCARD NUMBER     : ############1471\\nDATE/TIME       : 25 May 20 17:26:24\\nREFERENCE #     : 011 0108422 M\\nAUTHOR. #       : ET5626\\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":"XXXXXXX","transaction_type":"00","amount":5.0,"cc_number":"############1471","transaction_tag":4302924084,"authorization_num":"ET5626","cc_expiry":"1122","cardholder_name":"John Doe","cvd_presence_ind":1,"currency_code":"USD","partial_redemption":0,"credit_card_type":"Mastercard"}'

API request example (simulating a decline):
(simulation values for Demo terminals: https://support.payeezy.com/hc/en-us/articles/204504185) 

{
"cc_number": "XXXXXXX", 
"cardholder_name":"John Doe",
"transaction_type": "00",
"cc_expiry": "1122",
"amount": "5.00",
"gateway_id": "XXXXXX",
"password": "XXXXXXXXX", 
"cvd_code":"234",
"cvd_presence_ind":"1"
}

API response example:
'{"transaction_error":1,"transaction_approved":0,"exact_resp_code":"08","exact_message":"CVV2/CID/CVC2 Data not Verified","bank_resp_code":"100","bank_message":"Approved","bank_resp_code_2":"01","sequence_no":"0019513","cvv2":"N","retrieval_ref_no":"200525","merchant_name":"XXXXXX","merchant_address":"3722 Crenshaw Blvd","merchant_city":"Los Angeles","merchant_province":"California","merchant_country":"United States","merchant_postal":"90016","merchant_url":"https://admin.gateway.payeezyqa.com","ctr":"========== TRANSACTION RECORD ==========\\nXXXXXX \\n3722 Crenshaw Blvd\\nLos Angeles, CA 90016\\nUnited States\\nhttps://XXXXXXX.com\\n\\nTYPE: Purchase\\n\\nACCT: Mastercard              $ 5.00 USD\\n\\nCARDHOLDER NAME : John Doe\\nCARD NUMBER     : ############1471\\nDATE/TIME       : 25 May 20 17:33:36\\nREFERENCE #     : 011 0019513 M\\nAUTHOR. #       : \\nTRANS. REF.     : \\n\\n    Transaction not completed\\n\\n\\nPlease retain this copy for your records.\\n========================================","gateway_id":"XXXXXXXXXX","transaction_type":"00","amount":5.0,"cc_number":"############1471","transaction_tag":4302924172,"authorization_num":"ET0338","cc_expiry":"1122","cardholder_name":"John Doe","cvd_presence_ind":1,"currency_code":"USD","partial_redemption":0,"credit_card_type":"Mastercard"}'

3.1 PayPal Transactions

Merchants that want to use the API to process PayPal Authorization transactions should first integrate directly with PayPal. (https://developer.paypal.com/) 

The API functionality exposed via Payeezy Gateway allows for the following actions:

• Record of a PayPal “Authorization”, “Capture”, and “Order” (that was processed directly via PayPal API) on the Payeezy Gateway database. Record calls are typically done so  that a merchant can see the details in RPM Transaction Details and Reports and also act on these transactions using the Payeezy Gateway platform (via actions on RPM or API). 
• Complete/Void/Refund of an existing PayPal transaction that is recorded on Payeezy Gateway database. (The original transaction must be authorized directly via PayPal API or via PGW Payment Page using PayPal as the method of payment.)

Note: voids can only be run against authorized transactions that are not yet settled. To return funds that have already been settled to a customer, the tagged refund transaction type must be used.
PayPal authorizations will expire if they are not completed on time. Please refer to the official PayPal documentation for the expiration timeline: https://developer.paypal.com/docs/integration/direct/payments/authorize-and-capture-payments/#overview

Note: Payeezy Gateway integrates into PayPal NVP/SOAP API (https://developer.paypal.com/docs/classic/product-info/)

PayPal error codes: https://developer.paypal.com/docs/classic/api/errors/ 

API versions and supported features

• Recording of PayPal transactions and Void/Refund of PayPal transactions are supported starting from Payeezy Gateway API v10 and above
• For API v31 and above, API field “message” can be shown in RPM Transactions Details under field name “Bank Response”. This way, the merchant can record and keep track of the PayPal response that was received. In API versions below v31 “Bank Response” shows First Data Bank Response Codes (documented here: https://support.payeezy.com/hc/en-us/articles/203730509).
• “code” field in Payeezy Gateway API is supported from version 31 and above. It will show in RPM Transaction Details in the UI field “Bank Response”, beside the PayPal “message” string.

PayPal Transaction Types in Payeezy Gateway 

Payeezy Gateway PayPal Properties

The following PayPal properties are used to record PayPal transactions on Payeezy Gateway. These PayPal transactions have already been processed by PayPal. To use any of the PayPal transaction types, the "credit_card_type" property must be set to "PayPal". Note that the below properties are only applicable to PayPal Purchase, Pre-Authorization, and Order transactions. To perform a tagged refund, pre-authorization completion, or void against a PayPal transaction, the normal tagged transaction types can be used. Alternatively, tagged transactions can be performed through the RPM user interface.

API request example (JSON). Use case: record a PayPal “Order” on Payeezy Gateway. (A merchant already processed the “Order” against PayPal API)

{

"gateway_id":"X61234-12",

"amount":21.00,

"transaction_type":"07",

"credit_card_type":"PayPal",

"cardholder_name":" Simon Jones",

"password":"secret",

"paypal_transaction_details": {

"correlation_id":"DEFCAB77889900",

"timestamp":" 2019-05-26T08 : 52 : 29Z",

"authorization":"O-123456789ABCDEFGH",

"payer_id":"ABCDEF1234567890",

"gross_amount_currency_id":"USD",

"success":true,

"message":"What a wonderful world !",
“code”:”12345”}

}

API response example
{"transaction_error":0,"transaction_approved":1,"exact_resp_code":"00","exact_message":"Transaction Normal","bank_resp_code":"100","bank_message":"What a wonderful world!","merchant_name":"Amazing Shopping","merchant_address":"3722 Crenshaw Blvd","merchant_city":"Los Angeles","merchant_province":"California","merchant_country":"United States","merchant_postal":"90016","merchant_url":"https://amazing-shopping.com","ctr":"========== TRANSACTION RECORD ==========\\nAmazing Shopping \\n3722 Crenshaw Blvd\\nLos Angeles, CA 90016\\nUnited States\\nhttps://admin.gateway.payeezyqa.com\\n\\nTYPE: Purchase\\n\\nACCT: PayPal                 $ 21.00 USD\\n\\nCARDHOLDER NAME : Simon Jones\\nCARD NUMBER : \\nDATE/TIME : 27 Aug 19 20:40:44\\nREFERENCE # : 011 M\\nAUTHOR. # : PP1044\\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":"X61234-12","transaction_type":"00","amount":21.0,"transaction_tag":5000068055,"authorization_num":"PP1044","cardholder_name":"Simon Jones","cvd_presence_ind":0,"currency_code":"USD","partial_redemption":0,"credit_card_type":"PayPal","paypal_transaction_details":{"payer_id":"ABCDEF1234567890","gross_amount_currency_id":"USD","success":true,"authorization":”O-123456789ABCDEFGH”,"message":"What a wonderful world!","correlation_id":"DEFCAB77889900","timestamp":"2019-05-26T08 : 52 : 29Z","code":"12345"}}'

API request example (JSON). Use case: tagged-refund of a PayPal “Capture” via Payeezy Gateway. (A merchant sends API request to Payeezy Gateway. Payeezy Gateway will contact PayPal API to initiate the refund)

{

"gateway_id":"X61234-12",
"password":"secret",

"transaction_type":"34",
"transaction_tag":"5012368457",
"amount":2.00,

}

API response example

{"transaction_error":0,"transaction_approved":1,"exact_resp_code":"00","exact_message":"Transaction Normal","bank_resp_code":"100","bank_message":"Success","amount_requested":0.0,"merchant_name":"Respect Elders","merchant_address":"3722 Crenshaw Blvd","merchant_city":"Los Angeles","merchant_province":"California","merchant_country":"United States","merchant_postal":"90016","merchant_url":"https://admin.gateway.payeezyqa.com","ctr":"========== TRANSACTION RECORD ==========\\nRespect Elders \\n3722 Crenshaw Blvd\\nLos Angeles, CA 90016\\nUnited States\\nhttps://admin.gateway.payeezyqa.com\\n\\nTYPE: Refund\\n\\nACCT: PayPal                  $ 2.00 USD\\n\\nCARDHOLDER NAME : Mike Angelo \\nCARD NUMBER : \\nDATE/TIME : 30 Aug 19 19:44:29\\nREFERENCE # : 011 M\\nAUTHOR. # : PP1429\\nTRANS. REF. : \\n\\n Approved - Thank You 100\\n\\n\\nPlease retain this copy for your records.\\n========================================","gateway_id":"X61234-12","transaction_type":"34","amount":2.0,"transaction_tag":5000068457,"authorization_num":"PP1429","cardholder_name":"Mike Angelo","cvd_presence_ind":0,"currency_code":"USD","partial_redemption":0,"credit_card_type":"PayPal","paypal_transaction_details":{"payer_id":"AYAFAZKPZ9XPC","gross_amount_currency_id":"USD","success":true,"authorization":"PP1121","message":null,"correlation_id":"a70f86192bccb","timestamp":"2019-08-30T22:14:29Z"}}'

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 and merchants can do a secondary transaction (Refund/Void) against it via Transaction Search in the RPM

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

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 Card Transactions (Gift Solutions)

This section is specifically oriented on Gift Card transaction processing via API. For a general overview of the Gift Card feature please refer to the Gift Solutions Gift Cards Overview for Payeezy Gateway article.
Gift Solutions gift cards are supported by the Payeezy Gateway API. Gift Solutions cards are treated as a method of payment such as credit cards. Payeezy Gateway is certified SVdot Internet message format through Compass host.

Please note: When processing gift card transactions, API version 9 or higher should be used for EAN cards and cards without security code. For SCV cards API version 26 or higher is needed.

Each type of the gift card transaction has its own optional and required properties, which are listed in the table below.

Mandatory usage of gift card security codes

If a gift card type is SCV or EAN, then the SCV or EAN fields must be populated with the relevant gift card security number. If not populated, then the transaction will be rejected. No need to use SCV or EAN fields for Pinless cards.

Virtual vs. Physical cards

To indicate that a gift card is Virtual, please use the following boolean field:
JSON: "virtual_card": true
XML: <VirtualCard>true</VirtualCard>

For Physical gift cards no need to use this field.

Gift Card Transaction example

Sample JSON request for EAN Virtual card

{

"cc_number": "1234123412341234",

"gateway_id": "XX1234-12",

"transaction_type": "00",

"credit_card_type": "gift",

"virtual_card": true,

 "password": "samplepassword",

 "cardholder_name": "Simone Sample",

 "amount": "6",

 "ean": "12345678",

 "post_date": "02192016",

 "signature": "9b8e669eda16e2cf16ca43ad39f6191471c32bae"

}

Response for sample request

{

 "transaction_error": 0,

 "transaction_approved": 1,

 "exact_resp_code": "00",

 "exact_message": "Transaction Normal",

 "bank_resp_code": "100",

 "bank_message": "Approved",

 "sequence_no": "000002",

 "retrieval_ref_no": "1417459",

 "merchant_name": "Testing 001",

 "merchant_address": "1234 Main st.",

 "merchant_city": "Atlanta",

 "merchant_province": "Georgia",

 "merchant_country": "United States",

 "merchant_postal": “54321",

 "merchant_url": "http://www.firstdata.com",

 "current_balance": 4.0,

 "previous_balance": 10.0,

"ctr": "========== TRANSACTION RECORD ==========\nTesting 001\n1234 Main st.\nAtlanta, GA 30342\nUnited States\nhttp://www.firstdata.com\n\nTYPE: Purchase\n\nACCT: Gift Card               $ 6.00 USD\n\nCARDHOLDER NAME : Simone Sample\nCARD NUMBER     : ############1234\nDATE/TIME       : 15 Jan 16 19:16:27\nREFERENCE #     : 001 000002 M\nAUTHOR. #       : ET121643\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\ncard issuer pursuant to cardholder\nagreement.\n========================================",

 "gateway_id": "XX1234-12",

 "transaction_type": "00",

 "amount": 6.0,

 "cc_number": "############1234",

 "transaction_tag": 5508,

 "authorization_num": "ET121643",

 "cardholder_name": "Simone Sample",

 "cvd_presence_ind": 0,

 "currency_code": "USD",

 "partial_redemption": 0,

 "credit_card_type": "Gift Card",

 "ean": "12345678",

 "post_date": "02192016",

 "valuelink_auth_code": "100",

 "local_currency_code": "840"

}

Split Tender via API

Note that partial authorizations are enabled for gift card 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.

Please note: this functionality is available in API v13 or higher.

API Request example (JSON)
{

  "gateway_id": "XX1234-12",

  "password": "12345pwd",

  "amount":150.00,

  "transaction_type": "00",

  "credit_card_type": "gift", 

  "cardholder_name": "Simone Sample",

  "cc_number": "1234123412341234",

  "scv":"12345678",

  "virtual_card": true,

}

Response example (JSON)

{
"transaction_type": "00", 
"amount": "100.0", 
"card_number": "############4235", 
"transaction_tag": "2200930149", 
"split_tender_id": "2200930149",
"authorization_num": "VL4580", 
"card_holdersname": "Simone Sample", 
"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", 
"sequence_no": "0101942", 
"currency": "USD", 
"amount_requested": "150.0", 
"partial_redemption": "true", 
"merchant_name": "test merchant", 
"credit_card_type": "Gift Card", 
"current_balance": "0.0", 
"previous_balance": "100.0", 
"virtual_card": "true", 
"ctr": "========== TRANSACTION RECORD ==========\nGift SCV Active Settlement\n, AL\nUnited States\nTYPE: Purchase\nACCT: Gift Card $ 300.00 USD\n ($ 350.00 USD was requested)\nCARDHOLDER NAME :Simone Sample\nCARD NUMBER : ############4235\nDATE/TIME : 14 Feb 18 08:51:44\nREFERENCE # : 001 0101942 V\nAUTHOR. # : VL4580\nTRANS. REF. : \n Approved - Thank You 100\nPlease retain this copy for your records.\nCardholder will pay above amount to\ncard issuer pursuant to cardholder\nagreement.\n========================================","value_link_auth_code": "101181", 
"local_currency_code": "840", 
"scv": "95083131"
}

3.4 TransArmor Transactions

Detailed explanation about the business logic of the TransArmor feature can be found here: https://support.payeezy.com/hc/en-us/articles/203731189

To check if the terminal is enabled for TransArmor in RPM, visit the Administration->Details tab. If the TransArmor Token field is populated then TransArmor is enabled. In a Demo environment, one can enable the TransArmor feature by populating the field with any random set of characters and numbers.  

Please note: the TransArmor token shown in RPM should not be confused with the "transarmor_token" API field. The RPM value is used as an encryption seed, whereas the API field is used to transfer the actual token of a specific card number.
The TransArmor token provided via Payeezy Gateway is a multi-pay token that can be used to represent the same credit card for all subsequent transactions for this specific card.

Card tokenization

When an API request is using the API field “cc_number” AND if TransArmor is enabled on a terminal, then the API response will include a field “transarmor_token” where a tokenized card number will be passed back. In addition, the “credit_card_type” field will be returned to indicate what card brand was used. 

Transactions that use the “transarmor_token” in an API request must include the “credit_card_type” field to identify the card brand. Without this field, a transaction will be rejected with the following HTTP error: ‘Bad Request (07) - Invalid Attribute (credit_card_type)’

To tokenize a card without processing a payment, submit a $0 pre-authorization transaction.

Please note: when using card tokenization, there is a need to use the feature Stored Credentials (see section 3.13 of the API spec).

For the field credit_card_type (json) CardType (XML/SOAP), the following values are valid for credit cards:
'MASTERCARD'
'VISA'
'AMERICAN EXPRESS'
'DINERS CLUB'
'DISCOVER'
'JCB'

Using TransArmor Tokens with a Test Account

In the production environment, when tokenizing a card number, the same TransArmor token will always be returned for a given credit card number (when the same terminal and same encryption seed is used). However, in the test environment, each time you tokenize a card number, a different TransArmor token will be returned. 

In both, TEST and PROD environments, the last 4 digits of the token are the same as the card number.

Please note that the API samples below work for Visa cards only. Other card brands require different fields with relation to Stored Credentials. Please refer to section 3.13.

Use case: Card tokenization with $0 Pre-Auth followed by a purchase

Card tokenization API request example using Visa (JSON)
{
  "cc_number": "4111111111111111",
  "cardholder_name":"Joe Bloggs",
  "transaction_type": "01",
  "cc_expiry": "0925",
  "amount": "0",
  "gateway_id": "XXXXXX-XX",
  "password": "XXXXXXX",

    "stored_credentials": {

   "indicator": "1",

   "initiation": "M",   

   "schedule": "U",

   "transaction_id”: ”new”

    }

}

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":"0308389","retrieval_ref_no":"200107","merchant_name":"MGZ","merchant_address":"123 Sesame Street","merchant_city":"New York","merchant_province":"New York","merchant_country":"United States","merchant_postal":"54321","ctr":"========== TRANSACTION RECORD ==========\\nMGZ\\n123 Sesame Street\\nNew York, NY 54321\\nUnited States\\n\\n\\nTYPE: Pre-Authorization\\n\\nACCT: Visa                    $ 0.00 USD\\n\\nCARDHOLDER NAME : Dr. Dolittle\\nCARD NUMBER : ############1111\\nDATE/TIME : 07 Jan 20 16:03:24\\nREFERENCE # : 003 0308389 T\\nAUTHOR. # : 348467\\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":"H45651-72","transaction_type":"01","amount":0.0,"transaction_tag":4301741860,"authorization_num":"348467","cc_expiry":"0925","cardholder_name":"Joe Bloggs","cvd_presence_ind":0,"currency_code":"USD","partial_redemption":0,

"transarmor_token":"9280353820081111", 

"credit_card_type":"Visa",

"stored_credentials":

{"indicator":"1","initiation":"M","schedule":"U","transaction_id":"750007704041294"}

}

Follow up purchase API request example using Visa (JSON); 
"transarmor_token", "credit_card_type", and "transaction_id" were provided in the response to the previous transaction
{
  "transarmor_token": "9280353820081111" ,
  "credit_card_type":"VISA",
  "cardholder_name":"Joe Bloggs",
  "transaction_type": "00",
  "cc_expiry": "0925",
  "amount": "5.25",
  "gateway_id": "XXXXXX-XX",
  "password": "XXXXXXX"

    "stored_credentials": {

   "indicator": "S",

   "initiation": "M",   

   "schedule": "U",

   "transaction_id”: ”750007704041294”

    }

}

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":"0242177","retrieval_ref_no":"200109","merchant_name":"MGZ","merchant_address":"123 Sesame Street","merchant_city":"New York","merchant_province":"New York","merchant_country":"United States","merchant_postal":"54321","ctr":"========== TRANSACTION RECORD ==========\\nMGZ\\n123 Sesame Street\\nNew York, NY 54321\\nUnited States\\n\\n\\nTYPE: Purchase\\n\\nACCT: Visa                    $ 3.25 USD\\n\\nCARDHOLDER NAME : Dr. Dolittle\\nCARD NUMBER : ############1111\\nDATE/TIME : 09 Jan 20 21:34:39\\nREFERENCE # : 003 0242177 T\\nAUTHOR. # : 655817\\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":"XXXX-XX","transaction_type":"00","amount":5.25,"transaction_tag":4301749947,"authorization_num":"655817","cardholder_name":"Joe Bloggs","cvd_presence_ind":0,"currency_code":"USD","partial_redemption":0,"transarmor_token":"9280353820081111","credit_card_type":"Visa","stored_credentials":{"indicator":"S","initiation":"M","schedule":"U","transaction_id":"750007704041294"}}

Use case: card tokenization with purchase included

API request example using Visa (JSON)
{
  "cc_number": "4111111111111111",
  "transaction_type": "00",
  "cardholder_name":"Joe Bloggs",
  "cc_expiry": "0925",
  "amount": "5.25",
  "gateway_id": "XXXXXX-XX",
  "password": "XXXXXXX",

   "stored_credentials": {

   "indicator": "1",

   "initiation": "M",   

   "schedule": "U",

   "transaction_id”: ”new”

    }

}



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":"0332065","retrieval_ref_no":"200109","merchant_name":"MGZ settle 3","merchant_address":"123 Sesame Street","merchant_city":"New York","merchant_province":"New York","merchant_country":"United States","merchant_postal":"54321","ctr":"========== TRANSACTION RECORD ==========\\nMGZ settle 3\\n123 Sesame Street\\nNew York, NY 54321\\nUnited States\\n\\n\\nTYPE: Purchase\\n\\nACCT: Visa                    $ 5.25 USD\\n\\nCARDHOLDER NAME : Dr. Dolittle\\nCARD NUMBER : ############1111\\nDATE/TIME : 09 Jan 20 21:44:41\\nREFERENCE # : 003 0332065 T\\nAUTHOR. # : 436354\\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":"H45651-72","transaction_type":"00","amount":5.25,"transaction_tag":4301749948,"authorization_num":"436354","cardholder_name":"Joe Bloggs","cvd_presence_ind":0,"currency_code":"USD","partial_redemption":0,"transarmor_token":"9280353820081111","credit_card_type":"Visa","stored_credentials":{"indicator":"1","initiation":"M","schedule":"U","transaction_id":"750010044810915"}}'

3.5 Telecheck Transactions

The API v13 and higher versions support TeleCheck transactions.

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.

Note: Asterisk (*) are optional fields, only submit these fields when required by TeleCheck.

TeleCheck API request properties

API request example (Json)

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

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:

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:

Settings Properties

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

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

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

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

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.

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:

Response Status

Partial Shipping Address

Response to Payment Cancelled Events

Response to Error Events

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

3. 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"

}

Tagged 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:

Requesting a Debit Bill Pay transaction should follow similar structure to Credit Card transactions. However, please specify 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 (e.g., STAR, NYCE, PULSE).
In addition, "customer_ref" field must be populated with an alpha-numeric value (no longer than 20 characters). (customer_ref (JSON) , Customer_Ref (XML/SOAP)). A failure to populate this field may result in rejection with Bank Code 227 (Missing Companion Data).
Supported e-commerce flags for this feature are: 2, 7, I.

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

Request Sample (JSON):

{
"credit_card_type":"Debit Bill Pay",
"customer_ref":"12345abcdef",
"amount":"77.00",
"transaction_type":"00",
"cardholder_name":"Claudia Crooks",
"cc_number":"XXXXXXXXXXXXX",
"cc_expiry":"0920",

 }

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":"0149537","retrieval_ref_no":"200303","amount_requested":0.0,"merchant_name":"Settlement - Debit Bill Pay","merchant_address":"128 W 6th Ave","merchant_city":"Vancouver","merchant_province":"British Columbia","merchant_country":"Canada","merchant_postal":"BC V5Y 1K","ctr":"========== TRANSACTION RECORD ==========\nSettlement - Debit Bill Pay\n128 W 6th Ave\nVancouver, BC BC V5Y 1K\nCanada\n\n\nTYPE: Purchase\n\nACCT: NYCE Debit Bill Pay $ 77.00 USD\n\nCARDHOLDER NAME : Claudia Crooks\nCARD NUMBER : ############4453\nDATE/TIME : 03 Mar 20 13:44:43\nREFERENCE # : 001 0149537 M\nAUTHOR. # : 412586\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":"XXX","transaction_type":"00","amount":77.0,"cc_number":"############4453","transaction_tag":4300022270,"authorization_num":"412586","cc_expiry":"0920","cardholder_name":"Claudia Crooks", "partial_redemption":0,"credit_card_type":"Debit Bill Pay, "customer_ref":"12345abcdef"}

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>

<Customer_Ref>12345abcdef</Customer_Ref>

<Currency_Code>USD</Currency_Code>

</Transaction>

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>

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.

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)

API Request example (JSON):

{
"gateway_id": "XXXXXX-XXX",
"password": "XXXXXXX",
"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 transactions for Payment Facilitator are supported by API v23 and above.
• Transaction Search and Report API specification is available here: https://support.payeezy.com/hc/en-us/articles/203731129

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)

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.

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"

}

}

3.12 Timeout Reversal

Timeout reversal functionality is available on v19.  Timeout reversal allows for the inclusion of a unique identifier on transaction types that are eligible for a Tagged Void (00, 01, 32, and 34).  If a timeout occurs, the unique id can be utilized in an attempt to reverse the original transaction.

To utilize the timeout reversal functionality, the correlation_id field should be included on all transaction types mentioned above.  It is suggested that a GUID or UUID be used for the correlation_id value.  In the event of a transaction timeout, a Tagged Void (33) transaction type can be executed with a modified payload, removing the requirements for the authorization number and transaction tag values and in their place including the correlation_id value presented on the original transaction.  The original amount of the transaction is also required.

Sample Authorization Payload (JSON) 

{

    "amount": 1.1,

    "cardholder_name": "Tester CorrID",

    "cc_expiry": "0419",

    "cc_number": "XXXX XXXX XXXX XXXX ",

    "gateway_id": "XXXXXX",

    "password": "XXXXXX",

    "transaction_type": "00",

"correlation_id": "8bbecc96-08e4-49fe-96f9-a65171bfc752"

} 

Sample Timeout Reversal Payload (JSON) 

{

    "amount": 1.1,

    "gateway_id": "xxxxx",

    "password": "xxxxx",

    "transaction_type": "33",

"correlation_id": "8bbecc96-08e4-49fe-96f9-a65171bfc752"

}

Failure to pass a unique correlation_id will result in ETG Code 88 – “Invalid Correlation ID” being returned.

If the transaction has been previously reversed, a response code of 69 – “Invalid Transaction Tag” will be returned.

If the amount is missing or does not match, or the original transaction was never executed, you will receive a 404 response with a “No transaction found for correlation_id” message in the body.

Timeout reversals should be executed immediately following a timeout.

3.13 Stored Credentials (also known as Credentials-on-File)

The purpose of this feature is to identify the card on file/stored credentials transaction type. It is available via API v28 and higher. The feature is supported for Visa, Mastercard, Discover, and Amex.

For Mastercard transactions, these credentials must be sent for non-Canadian merchants only; data fields are ignored if sent for Canadian merchants (in this case the transaction will be processed as a regular credit card transaction and the API fields for Stored Credentials won't be returned in the API response).

Stored Credentials API fields are optional. However, if the Stored Credentials fields are submitted, they must be populated with valid values. Otherwise, the transaction may be rejected or processed as a regular credit card transaction.

Please note: if the transaction is approved, but the fields for Stored Credentials are not returned back in the API response, then the transaction is not processed as Stored Credentials. The reason: the API request with regards to Stored Credentials was not structured properly (e.g., typo in the field name) and hence these fields were dropped.

Please refer to the table below for the list of allowed values
(This table is applicable for Visa, Mastercard, and Discover. See a separate section for American Express)

Stored Credentials for American Express

The usage of Stored Credentials for American Express is different from other card brands. For American Express the e-commerce flag defines if the transaction is Stored Credentials type or not. “stored_credentials” field shouldn’t be used for American Express transactions.

E-commerce flag is an API field: “ecommerce_flag” (JSON) and “Ecommerce_Flag” (SOAP/XML)

Sample API request in JSON format (Visa card)

{

 "cc_number": "4111111111111111",

 "cc_expiry": "0418",

 "cardholder_name": "Simon Jones",

 "gateway_id": "AD0123-01",

 "password": "sample_password",

 "transaction_type": "00",

 "amount": 12,

 "stored_credentials": {

   "indicator": "1",
   "initiation": "M",   
   "schedule": "S",
   "transaction_id”: ”new”

 }

}

Sample Response in JSON format (Visa card)

{
 "transaction_error": 0,
 "transaction_approved": 1,
 "exact_resp_code": "00",
 "exact_message": "Transaction Normal",
 "bank_resp_code": "100",
 "bank_message": "Approved",
 "sequence_no": "Replaced sequence_no",
 "cvv2": "Replaced cvv2",
 "retrieval_ref_no": "Replaced retrieval_ref_no",
 "merchant_name": "Settlement - API Testing (Generic) 001",
 "merchant_address": "1 API CAD Terminal Way",
 "merchant_city": "Toronto",
 "merchant_province": "Ontario",
 "merchant_country": "Canada",
 "merchant_postal": "M4B 1B3",
 "merchant_url": "Replaced merchant_url",
 "ctr": "========== TRANSACTION RECORD ==========\nSettlement - API Testing (Generic) 001\n1 API CAD Terminal Way\nToronto, ON M4B 1B3\nCanada\n\n\nTYPE: Purchase\n\nACCT: Visa                   $ 12.00 USD\n\nCARDHOLDER NAME : Simon Jones\nCARD NUMBER : ############1111\nDate/Time : REPLACED_DATE_TIME\nREFERENCE : REPLACED_REFERENCE_NNOO\nAUTHOR. : REPLACED_AUTHORICE_NNOO\nTRANS. REF.   : REPLACED_TRANS. 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": "Replaced gateway_id",
 "transaction_type": "00",
 "amount": 12.0,
 "cc_number": "############1111",
 "transaction_tag": "Replaced transaction_tag",
 "authorization_num": "Replaced authorization_num",
 "cc_expiry": "Replaced cc_expiry",
 "cardholder_name": "Simon Jones",
 "cvd_presence_ind": 0,
 "currency_code": "USD",
 "partial_redemption": 0,
 "credit_card_type": "Visa",
 "stored_credentials": {
   "indicator": "1",
   "initiation": "M",
   "schedule": "S",
   “transaction_id”: ”098765432154321”
 },
 "cavv_response": "Replaced cavv_response",
 "client_ip": "Replaced client_ip",
 "bank_resp_code_2": "Replaced bank_resp_code_2",
 "reference_no": "Replaced reference_no"
}

Sample API request in JSON format (American Express card)
example of a recurring transaction

{

 "cc_number": "340000000000009",

 "cc_expiry": "0920",

 "cardholder_name": "Simon Jones",

"ecommerce_flag": "2",

 "gateway_id": "AB0123-01",

 "password": "sample_password",

 "transaction_type": "00",

 "amount": "20.00",

}

Sample Response in JSON format (American Express card)

{"transaction_error":0,"transaction_approved":1,"exact_resp_code":"00","exact_message":"Transaction Normal","bank_resp_code":"100","bank_message":"Approved","sequence_no":"0619824","retrieval_ref_no":"190715","merchant_name":"some name","merchant_address":"675 main st.","merchant_city":"los angelese","merchant_province":"California","merchant_country":"United States","merchant_postal":"87664","merchant_url":"https://payeezy.com","ctr":"========== TRANSACTION RECORD ==========\\njhgkjh\\n675 main st.\\nlos angelese, CA 87664\\nUnited States\\nhttps://payeezy.com\\n\\nTYPE: Purchase\\n\\nACCT: American Express       $ 20.00 USD\\n\\nCARDHOLDER NAME :Simon Jones\\nCARD NUMBER     : ###########0009\\nDATE/TIME       : 15 Jul 19 17:44:21\\nREFERENCE #     : 002 0619824 M\\nAUTHOR. #       : 200316\\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":"AB0123-01",
"transaction_type":"00","amount":20.0,"cc_number":"###########0009","transaction_tag":4301233334,"authorization_num":"200316","cc_expiry":"0920","cardholder_name":"Simon Jones",
"cvd_presence_ind":0,"ecommerce_flag":"2","currency_code":"USD","partial_redemption":0,"credit_card_type":"American Express"}

3.14 Visa Non Original Credit Account Funding
Transaction (NON-OCT AFT)

Visa Non-OCT (Original Credit Transactions) enable the movement of funds to a Visa card account. Merchants or vendors that use Visa Non-OCT can facilitate services such as money transfers, government & merchant disbursements, etc. This program offerings require special client vetting, a separate merchant identifier (Division Number), and client contracts prior to beginning processing. Merchants or vendors performing money transfers must be state licensed Money Services Business (MSBs).

The supported card brand is Visa only.

Supported API version
API version should be v29 or above.

A new top-level API field is introduced to pass Visa NON-OCT AFT Transfer Type values:
● aft_transfer_type (JSON)
● AFTTransferType (XML/SOAP)

NON-OCT AFT Transfer Type will be shown in Transaction Details:

Submission of Merchant Category Code (MCC)

Please ensure that First Data sets up the processing terminal with the MCC code appropriate
for your merchant category. Alternatively, it is also possible to submit the MCC code via Soft
Descriptors (Please refer to API spec section “ Soft Descriptor Properties ”).

If the NON-OCT AFT Transfer Type value is not one of the permitted MCC code for a terminal,
then the transaction will be rejected with Bank Response Code ` 249 Invalid MCC `

Bank Response code will be shown in Transaction Details:

Transactions with wrong aft_transfer_type or with non-Visa card brand will be processed as
regular credit card transactions. However, submitting an AFT Transfer Type with more than 2
characters will result in an error response of “Bad Request (07) - Invalid Attribute
(aft_transfer_type).” When submitting an AFT Transfer Type for a non-Visa card type, it will be
ignored, but returned in the response.

Visa NON-OCT AFT API request example

{
"gateway_id":"XXXX",
"password":"XXXXXX",
"transaction_type":"00",
"amount":"110.12",
"cardholder_name":"Jon Sample",
"cc_number":"XXXXXXX",
"cc_expiry":"XXXX",
"aft_transfer_type":"AA",
}

Visa NON-OCT AFT API response example

{"transaction_error":0,
"Transaction_approved":1,
"Exact_resp_code":"00",
"exact_message":"Transaction Normal",
"Bank_resp_code":"100",
"bank_message":"Approved",
"Sequence_no":"0176417",
"Retrieval_ref_no":"190322",
"merchant_name":"FDT Terminal ACTIVE Shop",
"merchant_province":"Alabama",
"merchant_country":"United States",
"Merchant_postal":"90210",
"ctr":"========== TRANSACTION RECORD ==========\nFDT Terminal ACTIVE Shop\n\n,
AL 90210\nUnited States\n\n\nTYPE: Purchase\n\nACCT: Visa $ 110.12

USD\n\nCARDHOLDER NAME : Jon Sample\nCARD NUMBER :
############0018\nDATE/TIME : 22 Mar 19 12:36:40\nREFERENCE # : 001 0176417
M\nAUTHOR. # : 121450\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":"K02131-65",
"Transaction_type":"00",
"Amount":110.12,
"cc_number":"############0018",
"Transaction_tag":2200900311,
"Authorization_num":"121450",
"Cc_expiry":"1225",
"cardholder_name":"Jon Sample",
"Cvd_presence_ind":0,
"currency_code":"USD",
"Partial_redemption":0,
"credit_card_type":"Visa",
"aft_transfer_type":"AA" }

3.15 3DS version 2

Mastercard is enhancing the Mastercard Identity Check™ and Accountholder Authentication Value (AAV) verification services as part of the EMV™ 3-D secure authentication protocol for e-commerce transactions. By providing the new 3DS v2 info, Mastercard will help issuers to associate a Mastercard Identity Check™ transaction with its subsequent authorization. (EMV refers to EMV Co., the standards organization, not chip-based acquiring)

Presently the feature is limited to Mastercard’s new implementation of 3D Secure version 2. 

Please use API v30 or later for this feature.

The info must be provided by those merchants who are participating in the Mastercard Identity Check™ (SecureCode) program when the Program Protocol and Transaction ID values are returned by the plug-ins. These fields are pass-through from First Data perspective, and the merchants need to coordinate with their merchant plug-in (MPI) to receive the Directory Server Transaction ID.
Please note that the AAV (Accountholder Authentication Value) must be provided as part of the API request (using the “cavv” API field).

Example of API request (JSON). Mastercard 3D Secure version 2 transaction.

{
“gateway_id”:  "XXXXXXX-XX",
“transaction_type”: "00",
“amount”: "120.25",
“cc_number”: "XXXXXXXXXXXXXXXX", 

“cc_expiry”: "0619",
“cardholder_name”: "Simon Jones",
“three_d_secure_program_protocol”: "2",
“three_d_secure_directory_server_transaction_id”: "XXXXXXXXX",
“cavv”: “XXXXXXXXX”

}

Example of API response (JSON). Mastercard 3D Secure version 2 transaction.

{

 "transaction_error": 0,

 "transaction_approved": 1,

 "exact_resp_code": "00",

 "exact_message": "Transaction Normal",

 "bank_resp_code": "100",

 "bank_message": "Approved",

 "sequence_no": "Replaced sequence_no",

 "retrieval_ref_no": "Replaced retrieval_ref_no",

 "merchant_name": "Settlement - API Testing (Generic) 001",

 "merchant_address": "1 API CAD Terminal Way",

 "merchant_city": "Toronto",

 "merchant_province": "Ontario",

 "merchant_country": "Canada",

 "merchant_postal": "M4B 1B3",

 "merchant_url": "Replaced merchant_url",

 "ctr": "========== TRANSACTION RECORD ==========\nSettlement - API Testing (Generic) 001\n1 API CAD Terminal Way\nToronto, ON M4B 1B3\nCanada\n\n\nTYPE: Purchase\n\nACCT: Mastercard                  $ 120.25 USD\n\nCARDHOLDER NAME : Simon Jones\nCARD NUMBER : ############5454 \nDate/Time : REPLACED_DATE_TIME\nREFERENCE : REPLACED_REFERENCE_NNOO\nAUTHOR. : REPLACED_AUTHORICE_NNOO\nTRANS. REF.   : REPLACED_TRANS. 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": "XXXXXXX",

 "transaction_type": "00",

 "amount": 120.25,

 "cc_number": "############5454",

 "transaction_tag": "Replaced transaction_tag",

 "authorization_num": "Replaced authorization_num",

 "cc_expiry": "Replaced cc_expiry",

 "cardholder_name": "Simon Jones",

 "cvd_presence_ind": 0,
"cavv": "XXXXXXXXXXXX", 

 "currency_code": "USD",

 "partial_redemption": 0,

 "credit_card_type": "Mastercard",

 "three_d_secure_program_protocol": "2",

 "three_d_secure_directory_server_transaction_id": "XXXXXXX",

 "cavv_response": "Replaced cavv_response",

 "transarmor_token": "Replaced transarmor_token",

 "client_ip": "Replaced client_ip",

 "bank_resp_code_2": "Replaced bank_resp_code_2",

 "reference_no": "Replaced reference_no"

}

3.16 Business Application Indicator (BAI)

The feature is supported for PGW API version 31 and up.
Please note: this feature is not compatible with Transarmor

New field 'ba_indicator' (JSON) nested under the 'extra' object.
(<BaIndicator> in XML/SOAP format)

The API transaction will be processed as a BAI transaction under the following conditions:

• 'ba_indicator' must be sent as ​'​CB​' (upper case)
• 'aft_transfer_type' field must be blank or not sent.
• terminal is enabled for BAI (via RPM)
• card used must be VISA
• one of the following transaction types : purchase, pre-authorization, tagged completion (tagged completion will be processed as BAI even if the ba_indicator is not sent, if the original transaction was processed as BAI)

If the API transaction was processed as a BAI transaction, the possible values for 'ba_indicator' in the response are : 

• if the transaction is approved : "Approved"
• if the transaction is declined : "Declined"
• if the transaction received an error (ETG) : "Not processed"

Please ensure to check the 'ba_indicator' value in the response to ensure that the transaction is processed as BAI transaction.

API request example (JSON)
{
  "transaction_type" : "00",
  "cardholder_name" : "Simon Jones",

  "cc_number"" : "4111111111111111",

  "cc_expiry" : "0922",

  "amount" : "20.00",

  "extra": {

    "ba_indicator":"CB"   //please note the upper case for CB

  }

}

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":"000007",

  "cvv2":"I",

  "retrieval_ref_no":"210521",

  "merchant_name":"Testing merchant",

  "merchant_address":"3393 Peachtree Road NE",

  "merchant_city":"Atlanta",

  "merchant_province":"Georgia",

  "merchant_country":"United States",

  "merchant_postal":"30342",

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

  "ctr":"========== TRANSACTION RECORD ==========\\nTesting merchant\\n3393 Peachtree Road NE\\nAtlanta, GA 30342\\nUnited States\\nhttp://www.firstdata-demo-account.com\\n\\nTYPE: Purchase\\n\\nACCT: Visa                   $ 20.00 CAD\\n\\nCARDHOLDER NAME : Simon Jones\\nCARD NUMBER     : ############1111\\nDATE/TIME       : 21 May 21 21:01:50\\nREFERENCE #     : 002 000007 M\\nAUTHOR. #       : ET171722\\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\\ncard issuer pursuant to cardholder\\nagreement.\\n========================================",

  "gateway_id":"XXXXXXXXX",

  "transaction_type":"00",

  "amount":20.0,

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

  "transaction_tag":2147484394,

  "authorization_num":"ET171722",

  "cc_expiry":"0922",

  "cardholder_name":"Simon Jones",

  "cvd_presence_ind":0,

  "currency_code":"CAD",

  "partial_redemption":0,

  "credit_card_type":"Visa",

  "extra": {

    "ba_indicator":"Approved"

  }

}

3.17 Foreign Access Code (FAC)

Non-ValueLink gift cards that use Foreign Access.

Prior to usage, please confirm with your merchant support manager that your terminal is properly setup to accept non-ValueLink gift cards.

This feature works with API v32 and above.

For general review of the Payeezy Gateway API spec and gift card feature, please follow the URL:
https://support.payeezy.com/hc/en-us/articles/206601408

The processing for FAC cards is similar to regular gift cards (the above URL), but a Foreign Access Code needs to be provided for each transaction.

A new field is added: 
foreign_access_code (JSON format)
<ForeignAccessCode> (XML format)

Please note that "foreign_access_code" should be used inside the object "Extra"

Example: 

(JSON format)

"extra"  {

  "foreign_access_code" : "1234"

}

(XML format)

<Extra>

   <Field>ForeignAccessCode</Field>

   <Value>12345</Value>

</Extra>

FAC API examples are given in the XML format. However, JSON and SOAP can be used as well. For more examples on how to use the API, please refer to https://support.payeezy.com/hc/en-us/articles/206601408

Activation API Request example (XML format):

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

<Transaction>

<ExactID>xxxx</ExactID>

<Password>xxxx</Password>

<DollarAmount>100.00</DollarAmount>

<Transaction_Type>85</Transaction_Type>

<CardHoldersName>William Ferguson</CardHoldersName>

<CardType>gift</CardType>

<Card_Number>XXXXXXXXXXXXXX</Card_Number>

<CardCost>100.00</CardCost>

<Extra>

   <Field>ForeignAccessCode</Field>

   <Value>XXXX</Value>

</Extra>

</Transaction>

Activation API Response example (XML format):

<TransactionResult>

 <ExactID>XXXXXXXXX</ExactID>

 <Password/>

 <Transaction_Type>85</Transaction_Type>

 <DollarAmount>100.0</DollarAmount>

 <SurchargeAmount/>

 <Card_Number>############7609</Card_Number>

 <Transaction_Tag>5000146805</Transaction_Tag>

 <SplitTenderID/>

 <Track1/>

 <Track2/>

 <PAN/>

 <Authorization_Num>VL0049</Authorization_Num>

 <Expiry_Date/>

 <CardHoldersName>William Ferguson</CardHoldersName>

 <CVD_Presence_Ind>0</CVD_Presence_Ind>

 <ZipCode/>

 <Tax1Amount/>

 <Tax1Number/>

 <Tax2Amount/>

 <Tax2Number/>

 <Secure_AuthRequired/>

 <Secure_AuthResult/>

 <Ecommerce_Flag/>

 <XID/>

 <CAVV/>

 <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>0354069</SequenceNo>

 <AVS/>

 <CVV2/>

 <Retrieval_Ref_No>201008</Retrieval_Ref_No>

 <CAVV_Response/>

 <Currency>USD</Currency>

 <AmountRequested>100.0</AmountRequested>

 <PartialRedemption>false</PartialRedemption>

 <MerchantName>Amazing Dreams</MerchantName>

 <MerchantAddress/>

 <MerchantCity/>

 <MerchantProvince>Alabama</MerchantProvince>

 <MerchantCountry>United States</MerchantCountry>

 <MerchantPostal/>

 <MerchantURL/>

 <TransarmorToken/>

 <CardType>Gift Card</CardType>

 <CurrentBalance>100.0</CurrentBalance>

 <PreviousBalance>0.0</PreviousBalance>

 <EAN/>

 <CardCost>100.0</CardCost>

 <VirtualCard>false</VirtualCard>

 <CTR>========== TRANSACTION RECORD ==========

Amazing Dreams

, AL

United States

TYPE: Activate Card

ACCT: Gift Card             $ 100.00 USD

           ($ 100.00 USD was requested)

CARDHOLDER NAME : William Ferguson

CARD NUMBER     : ############7609

DATE/TIME       : 08 Oct 20 13:09:59

REFERENCE #     : 001 0354069 M

AUTHOR. #       : VL0049

TRANS. REF.     :

   Approved - Thank You 100

Please retain this copy for your records.

Cardholder will pay above amount to

card issuer pursuant to cardholder

agreement.

========================================</CTR>

 <FraudSuspected/>

 <CVDCode/>

 <SplitShipmentNumber/>

 <ValueLinkAuthCode>904753</ValueLinkAuthCode>

 <LocalCurrencyCode>840</LocalCurrencyCode>

 <Extra>

   <Field>ForeignAccessCode</Field>

   <Value>####</Value>

 </Extra>

 <ThreeDSecureProgramProtocol/>

 <ThreeDSecureDirectoryServerTransactionId/>

</TransactionResult>

1:14

Purchase API Request example (XML format):

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

<Transaction>

<ExactID>xxxxx</ExactID>

<Password>xxxxx</Password>

<DollarAmount>25.00</DollarAmount>

<Transaction_Type>00</Transaction_Type>

<CardHoldersName>William Ferguson</CardHoldersName>

<CardType>gift</CardType>

<Card_Number>XXXXXXXX</Card_Number>

<Extra>

   <Field>ForeignAccessCode</Field>

   <Value>4307</Value>

</Extra>

</Transaction>

Purchase API Response example (XML format)

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

<TransactionResult>

 <ExactID>O02677-40</ExactID>

 <Password/>

 <Transaction_Type>00</Transaction_Type>

 <DollarAmount>25.0</DollarAmount>

 <SurchargeAmount/>

 <Card_Number>############7609</Card_Number>

 <Transaction_Tag>5000146806</Transaction_Tag>

 <SplitTenderID/>

 <Track1/>

 <Track2/>

 <PAN/>

 <Authorization_Num>VL1686</Authorization_Num>

 <Expiry_Date/>

 <CardHoldersName>William Ferguson</CardHoldersName>

 <CVD_Presence_Ind>0</CVD_Presence_Ind>

 <ZipCode/>

 <Tax1Amount/>

 <Tax1Number/>

 <Tax2Amount/>

 <Tax2Number/>

 <Secure_AuthRequired/>

 <Secure_AuthResult/>

 <Ecommerce_Flag/>

 <XID/>

 <CAVV/>

 <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>0372932</SequenceNo>

 <AVS/>

 <CVV2/>

 <Retrieval_Ref_No/>

 <CAVV_Response/>

 <Currency>USD</Currency>

 <AmountRequested/>

 <PartialRedemption>false</PartialRedemption>

 <MerchantName>Amazing Dreams</MerchantName>

 <MerchantAddress/>

 <MerchantCity/>

 <MerchantProvince>Alabama</MerchantProvince>

 <MerchantCountry>United States</MerchantCountry>

 <MerchantPostal/>

 <MerchantURL/>

 <TransarmorToken/>

 <CardType>Gift Card</CardType>

 <CurrentBalance>75.0</CurrentBalance>

 <PreviousBalance>100.0</PreviousBalance>

 <EAN/>

 <CardCost/>

 <VirtualCard>false</VirtualCard>

 <CTR>========== TRANSACTION RECORD ==========

Amazing Dreams

, AL

United States

TYPE: Purchase

ACCT: Gift Card              $ 25.00 USD

CARDHOLDER NAME : William Ferguson

CARD NUMBER     : ############7609

DATE/TIME       : 08 Oct 20 13:13:16

REFERENCE #     : 001 0372932 M

AUTHOR. #       : VL1686

TRANS. REF.     :

   Approved - Thank You 100

Please retain this copy for your records.

Cardholder will pay above amount to

card issuer pursuant to cardholder

agreement.

========================================</CTR>

 <FraudSuspected/>

 <CVDCode/>

 <SplitShipmentNumber/>

 <ValueLinkAuthCode>637699</ValueLinkAuthCode>

 <LocalCurrencyCode>840</LocalCurrencyCode>

 <Extra>

   <Field>ForeignAccessCode</Field>

   <Value>####</Value>

 </Extra>

 <ThreeDSecureProgramProtocol/>

 <ThreeDSecureDirectoryServerTransactionId/>

</TransactionResult>

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 must be encoded in UTF-8 to ensure correct text display and processing. Using other encoding may result in rejected transactions.

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.

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

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.

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

This section was deprecated and merged to section 3.1.
Please refer to section 3.1 PayPal.

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. For Soft Descriptors to be used in settlement, one the following Soft Descriptor fields must be populated: "dba_name" or "mcc".
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 (https://support.payeezy.com/hc/en-us/articles/203730599).

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

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

4.7 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:

4.8 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:

SOAP / XML Example:

JSON Example:

4.9 Foreign Currency Details Properties

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