Payeezy

Overview

Gateway Website: https://globalgatewaye4.firstdata.com/
Developer Documentation: https://developer.payeezy.com/apis
Default Currency: USD

Request Objects: BillingAddress, CreditCard, Check, SoftDescriptors, StoredCredentials, ThreeDSecure

Gateway Endpoints
Production: https://api.payeezy.com/v1/
Test: https://api-cert.payeezy.com/v1/

Supported Request Parameters

^{* denotes a required field}

Field Name	Type	Payeezy Mapping	Notes
gateway	string	N/A	Payeezy
merchantId*	string	token	This is used to identify the merchant
privateKey*	string	apiKey	This is used to identify the app.
password*	string	apiSecret	This is your consumer secret.
amount*	numeric	amount	Transaction amount in smallest currency units. Example: $10.00 USD should be sent as 1000
tokenExTransactionCode	string	transaction_tag, transaction_id	Generated by this Payeezy implementation and available in the response gatewayResponse.tokenExTransactionCode. Required for capture, void, and refund actions. Optional for authorize and purchase.
merchantReferenceCode	string	merchant_ref	Merchant reference code – used by Payeezy system. Will be reflected in your Payeezy settlement records and webhook notifications.
feeAmount	numeric	fee_amount	Fee amount in smallest currency units. This is added to DollarAmount to produce the total charged. Specifying FeeAmount overrides any amount calculated for fees based on the configuration of the terminal. Ignored if fees are not enabled for terminal.
currencyCode	string	currency_code	Currency of the transaction. Use the ISO 4217 three-letter alphabetic code for the currency.
creditCard.Brand	string	credit_card.type	Optional. The card issuer brand name. Supported values: “American Express", "Visa", "Mastercard", “JCB”, “Diners Club” or "Discover"
creditCard.CVV	string	creditcard.cvv _or 3DS.cvv	The three- or four-digit number on the back of a credit card (on the front for American Express). This field is required if the merchant would like to use the Card Code Verification (CCV) security feature. Cardholder information must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard.
creditCard.FirstName	string	creditcard.cardholder_name _or 3DS.cardholder_name	The first name of the card holder. Concatenated with `CreditCard.LastName`. Example: "[firstName] [lastName]"
creditCard.LastName	string	creditcard.cardholder_name _or 3DS.cardholder_name	The last name of the card holder. Concatenated with `CreditCard.FirstName`. Example: "[firstName] [lastName]"
creditCard.Number	string	creditcard.card_number _or 3DS.card_number	Card number or TokenEx Token - TokenEx will replace the Token with the Detokenized number
creditCard.ExpMonth	string	creditcard.exp_date _or 3DS.exp_date	The two-digit expiration month of the card. Example: 03. Combined with `CreditCard.ExpYear` in MMYY format.
creditCard.ExpYear	string	creditcard.exp_date _or 3DS.exp_date	The four-digit expiration year of the card. Example: 2022. Combined with `CreditCard.ExpMonth` in MMYY format.
creditCard.SpecialPayment	string	creditcard.special_payment _or 3DS.special_payment	Special Payment works for Visa transactions only. For other cards this field will be ignored if passed. Payeezy merchant account has to be enabled in gateway to process as Special Payment.
billingAddress.Address1	string	billing_address.street	Customer’s billing address. Combined with `BillingAddress.Address2`
billingAddress.Address2	string	billing_address.street	Customer’s billing address, line 2. Combined with `BillingAddress.Address1`
billingAddress.State	string	billing_address.state_province	State/Province of customer’s billing address.
billingAddress.City	string	billing_address.city	City of customer’s billing address.
billingAddress.Country	string	billing_address.country	Alpha-3 ISO country code of the customer's billing address.
billingAddress.Email	string	billing_address.email	Email address associated with customer’s billing address.
billingAddress.Phone	string	billing_address.phone.number	Phone number associated with customer’s billing address.
billingAddress.PhoneType	string	billing_address.phone.type	Type of phone number. Example: Cell, Landline, Work.
softDescriptors.MerchantName*	string	soft_descriptors.dba_name	Business name.
softDescriptors.MerchantAddress.Address1	string	soft_descriptors.street	First line of the business address.
softDescriptors.MerchantAddress.Address2	string	soft_descriptors.street	Second line of the business address.
softDescriptors.MerchantAddress.City	string	soft_descriptors.city	City of the business address.
softDescriptors.MerchantAddress.State	string	soft_descriptors.region	State/Province of the business address.
softDescriptors.MerchantId	string	soft_descriptors.mid	Merchant ID.
softDescriptors.MerchantCategoryCode	string	soft_descriptors.mcc	Your merchant category code. Please see the Visa Merchant Data Standards manual for details.
softDescriptors.MerchantAddress.Zip	string	soft_descriptors.postal_code	Business postal/zip code.
softDescriptors.MerchantAddress.Country	string	soft_descriptors.country_code	Alpha-3 ISO country code of the business address.
softDescriptors.MerchantContactInfo	string	soft_descriptors.merchant_contact_info	Merchant contact information.
orderInfo.Subtotal	numeric	order_data.subtotal	Amount in smallest whole currency units before additional taxes.
tax.LocalTaxAmount	numeric	order_data.local_tax_amount	Local tax amount in smallest whole currency units.
tax.VatAmount	numeric	order_data.vat_amount	Value added tax amount in smallest whole currency units.
tax.Tax1Amount	numeric	level2.tax1_amount	Tax value included in total amount in smallest whole currency units. Only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the PST amount. Payeezy only supports Level II processing for Visa and MasterCard. It does not support American Express Level II processing.
tax.Tax1Number	string	level2.tax1_number	Registered number associated with the tax value. Used for reference or government claims purposes and only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the PST number. Payeezy only supports Level II processing for Visa and MasterCard. It does not support American Express Level II processing.
tax.Tax2Amount	numeric	level2.tax2_amount	Tax value included in total amount in smallest whole currency units. Only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the PST amount. Payeezy only supports Level II processing for Visa and MasterCard. It does not support American Express Level II processing.
tax.Tax2Number	string	level2.tax2_number	Registered number associated with the tax value. Used for reference or government claims purposes and only applicable to merchants passing level 2 (Corporate Credit Card - Level II) data. For Canadian merchants this field is the PST number. Payeezy only supports Level II processing for Visa and MasterCard. It does not support American Express Level II processing.
customerReferenceCode	string	level2.customer_ref	A merchant defined value that can be used to internally identify the transaction. It is passed on to the financial institution. The following characters will be stripped from this field: ; ` " / % as well as -- (2 consecutive dashes).
threeDSecure.Type	string	3DS.type	Takes the value “D“ indicating a Decrypted Apple Pay™ 3DS transaction.
threeDSecure.XID	string	3DS.xid	3DS transaction ID.
threeDSecure.CAVV	string	3DS.cavv	3DS value returned by Plug-in software application. For Mastercard it is AAV (Accountholder Authentication Value)
threeDSecure.WalletProviderId	string	3DS.wallet_provider_id	This is an optional field which enables Payeezy to identify the Mobile Wallet the transaction is originating from. Valid values for Wallet Provider Id are "NO_WALLET" (Default), "VISA_CHECKOUT", "MASTER_PASS", "APPLE_PAY" (Including the Web Apple Pay), "SAMSUNG_PAY", "ANDROID_PAY"
threeDSecure.ProgramProtocol	string	3DS.program_protocol	The 3D Secure protocol version to use. Can be either "1" or "2"; defaults to "1"
threeDSecure.ECI	string	eci_indicator	Electronic Commerce Indicator (ECI) is a value that is returned from the Directory Server (Visa®, MasterCard®, and JCB®) to indicate the authentication results of your customer credit card payment on 3DS.
threeDSecure.DSTransId	string	3DS.directory_server_transaction_id	This is a universally unique Transaction ID that the merchant should provide to Payeezy Gateway. This ID is sent back to merchant by 3-D Secure Merchant Plug-in software application. Note: DO NOT MANIPULATE this value in any way.
check.CheckNumber	string	tele_check.check_number	The check number.
check.AccountType	string	tele_check.check_type	Type of account from which the check will withdraw. Valid input Values 1 or Checking 2 or Savings 3 or GeneralLedger Payeezy mapping Checking - C Savings - S GeneralLedger - G
check.RoutingNumber	string	tele_check.routing_number	The nine-digit bank routing ("ABA") number for the customer's bank account.
check.AccountNumber	string	tele_check.account_number	Account number of the check or TokenEx Token - Tokenex will replace the Token with the Detokenized value
check.FirstName	string	tele_check.accountholder_name	The first name of the account holder. Combined with `Check.LastName` into this Payeezy field.
check.LastName	string	tele_check.accountholder_name	The last name of the account holder. Combined with `Check.FirstName` into this Payeezy field.
check.CustomerIdType	string	tele_check.customer_id_type	The type of identification the customer has provided.
check.CustomerIdNumber	string	tele_check.customer_id_number	The ID number of the provided customer identification.
check.ClientEmail	string	tele_check.client_email	Valid customer email address.
check.GiftCardAmount	numeric	tele_check.gift_card_amount	The amount in smallest whole currency units paid from a gift card.
check.VIP	string	tele_check.vip	Indicates VIP status for this transaction.
check.ClerkId	string	tele_check.clerk_id	The ID of the clerk generating the transaction.
check.DeviceId	string	tele_check.device_id	The ID of the device generating the transaction.
check.ReleaseType	string	tele_check.release_type	The fulfillment method of the order.
check.RegistrationNumber	string	tele_check.registration_number	Customer's merchant account registration number.
check.RegistrationDate	string	tele_check.registration_date	Customer's merchant account registration date. YYYY-MM-DD format.
check.DateOfBirth	string	tele_check.date_of_birth	Customer's date of birth. YYYY-MM-DD format.
storedCredentials.Initiator	string	stored_credentials.initiator	Valid values: "cardholder" or "merchant". These values are made upper case and then forwarded. Payeezy documentation
storedCredentials.CredentialStored	boolean	stored_credentials.sequence	See usage in The Basics - Stored Credentials. True = "SUBSEQUENT", False = "FIRST"
storedCredentials.PreviousNetworkTransactionId	string	stored_credentials.cardbrand_original_transaction_id	See usage in The Basics - Stored Credentials. Matches Payeezy response field "cardbrand_original_transaction_id".
storedCredentials.TransactionType	string	stored_credentials.isScheduled	Valid value mappings: "recurring" = true "installment" = true "unscheduled" = false any other string value = false *note: Authorize or Purchase requests that use values recurring or installment will change the Payeezy API eci_indicator to "2".
storedCredentials.CardBrandOriginalAmount	string	stored_credentials.cardbrand_original_amount	Passthrough. Payeezy documentation
storedCredentials.Amex	string	stored_credentials_amex	Passthrough. Payeezy documentation

📘
To indicate a transaction is recurring
To reference a previous transaction in an authorize or purchase action, send the relevant transaction's TokenExTransactionCode in the body. If the transaction was not processed by TokenEx's Payeezy implementation, it can still be processed by generating a value for the TokenExTransactionCode by base64 encoding the Payeezy transaction_id and transaction_tag in the following format: transaction_id;transaction_tag

Example Requests

{
  "gateway": "Payeezy",
  "testMode": true,
  "merchantId": "<Your Payeezy Merchant Token>",
  "password": "<Your Payeezy API Secret>",
  "privateKey": "<Your Payeezy API Key>",
  "amount": 1085,
  "currencyCode": "USD",
  "merchantReferenceCode": "834d031f-e3a5-4b51-866c-da1ad8a795ab",
  "softDescriptors": {
    "merchantName": "Oberbrunner - Bergnaum",
    "merchantCategoryCode": "3351",
    "merchantContactInfo": "5772798386",
    "merchantAddress": {
      "address1": "123 Someplace Lane",
      "address2": "Some Place",
      "city": "East Mariloustad",
      "state": "Pennsylvania",
      "zip": "01583-1892",
      "country": "USA"
    }
  },
  "storedCredentials": {
    "initiator": "merchant",
    "credentialStored": true,
    "previousNetworkTransactionId": "380220075428366",
    "transactionType": "installment",
    "cardBrandOriginalAmount": "10.85"
  },
  "creditCard": {
    "brand": "Discover",
    "number": "6510000000001248",
    "expMonth": 2,
    "expYear": 2024,
    "firstName": "Mark",
    "lastName": "Willms",
    "cvv": "339"
  },
  "billingAddress": {
    "phoneType": "Work",
    "phone": "95993749529139",
    "firstName": "Lorena",
    "lastName": "Feest",
    "address1": "123 Someplace Lane",
    "address2": "Some Place",
    "city": "Lake Kristoferfurt",
    "state": "Minnesota",
    "zip": "42861",
    "country": "USA"
  }
}

{
  "gateway": "Payeezy",
  "testMode": true,
  "merchantId": "<Your Payeezy Merchant Token>",
  "password": "<Your Payeezy API Secret>",
  "privateKey": "<Your Payeezy API Key>",
  "amount": 1085,
  "currencyCode": "USD",
  "merchantReferenceCode": "268ab12d-4ac8-4256-af38-a32e9e67e3f9",
  "tokenExTransactionCode": "<TokenExTransactioncode from a previous Card Authorize or Card Purchase>"
}

{
  "gateway": "Payeezy",
  "testMode": true,
  "currencyCode": "USD",
  "amount": 7,
  "merchantId": "<Your Payeezy Merchant Token>",
  "password": "<Your Payeezy API Secret>",
  "privateKey": "<Your Payeezy API Key>",
  "check": {
    "dateOfBirth": "2014-01-01",
    "registrationDate": "2014-01-01",
    "registrationNumber": "12345",
    "releaseType": "X",
    "deviceId": "jkhsdfjkhsk",
    "clerkId": "RVK_001",
    "vip": "n",
    "giftCardAmount": 0,
    "clientEmail": "[email protected]",
    "customerIdNumber": "7623786df",
    "customerIdType": "1",
    "accountNumber": "17101874",
    "routingNumber": "BN1234567801234567890",
    "checkNumber": "0101",
    "firstName": "Kelli",
    "lastName": "Tromp",
    "accountType": 1
  },
  "billingAddress": {
    "phoneType": "Cell",
    "phone": "18519217597182",
    "firstName": "Leona",
    "lastName": "Goodwin",
    "address1": "123 Someplace Lane",
    "address2": "Some Place",
    "city": "South Cleta",
    "state": "Michigan",
    "zip": "28256-6966",
    "country": "USA"
  }
}

{
  "gateway": "Payeezy",
  "testMode": true,
  "currencyCode": "USD",
  "amount": 7,
  "merchantId": "<Your Payeezy Merchant Token>",
  "password": "<Your Payeezy API Secret>",
  "privateKey": "<Your Payeezy API Key>",
  "tokenExTransactionCode": "<TokenExTransactionCode from a previous Check purchase>",
  "billingAddress": {
    "phoneType": "Cell",
    "phone": "12104721983",
    "firstName": "Woodrow",
    "lastName": "Ortiz",
    "address1": "123 Someplace Lane",
    "address2": "Some Place",
    "city": "Lake Frank",
    "state": "Missouri",
    "zip": "47917-1994",
    "country": "USA"
  }
}

Gateway Response Parameters

Field Name	Type	Payeezy Result Mapping	Notes
approved	boolean	validation_status & transaction_status	True if `validation_status` and `transaction_status` are "success" and "approved", respectively.
approvalCode	string	gateway_resp_code	Payeezy gateway Response code indicates the status of a transaction as it is sent to the financial institution and returned to the client.
providerTransactionCode	string	transaction_tag	The Transaction Tag is the unique order ID value assigned by Payeezy Gateway for every transaction processed and incremented by one each time. See this property's description in the Response section of the Payeezy Transaction API page for more information

Example Responses

{
    "gatewayResponse": {
        "rawResponse": "{\"correlation_id\":\"29.0198779959946\",\"transaction_status\":\"approved\",\"validation_status\":\"success\",\"transaction_type\":\"authorize\",\"transaction_id\":\"ET171779\",\"transaction_tag\":\"10123819340\",\"method\":\"credit_card\",\"amount\":\"500\",\"currency\":\"USD\",\"avs\":\"1\",\"cvv2\":\"I\",\"token\":{\"token_type\":\"FDToken\",\"token_data\":{\"value\":\"1407663716410026\"}},\"card\":{\"type\":\"Visa\",\"cardholder_name\":\"Frank Walter\",\"card_number\":\"0026\",\"exp_date\":\"0724\"},\"bank_resp_code\":\"100\",\"bank_message\":\"Approved\",\"gateway_resp_code\":\"00\",\"gateway_message\":\"Transaction Normal\",\"retrieval_ref_no\":\"231207\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "RVQxNzE3Nzk7MTAxMjM4MTkzNDA=",
        "approvalCode": "00",
        "providerTransactionCode": "10123819340",
        "approved": true
    },
    "referenceNumber": "23120716231815549424",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "201"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"correlation_id\":\"29.0198788921737\",\"transaction_status\":\"approved\",\"validation_status\":\"success\",\"transaction_type\":\"purchase\",\"transaction_id\":\"ET174974\",\"transaction_tag\":\"10123819374\",\"method\":\"credit_card\",\"amount\":\"500\",\"currency\":\"USD\",\"avs\":\"1\",\"cvv2\":\"I\",\"token\":{\"token_type\":\"FDToken\",\"token_data\":{\"value\":\"1403195903860026\"}},\"card\":{\"type\":\"Visa\",\"cardholder_name\":\"Frank Walter\",\"card_number\":\"0026\",\"exp_date\":\"0724\"},\"bank_resp_code\":\"100\",\"bank_message\":\"Approved\",\"gateway_resp_code\":\"00\",\"gateway_message\":\"Transaction Normal\",\"retrieval_ref_no\":\"231207\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "RVQxNzQ5NzQ7MTAxMjM4MTkzNzQ=",
        "approvalCode": "00",
        "providerTransactionCode": "10123819374",
        "approved": true
    },
    "referenceNumber": "23120716244778947567",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "201"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"correlation_id\":\"29.0198851351849\",\"transaction_status\":\"approved\",\"validation_status\":\"success\",\"transaction_type\":\"capture\",\"transaction_id\":\"ET195166\",\"transaction_tag\":\"10123819673\",\"method\":\"credit_card\",\"amount\":\"500\",\"currency\":\"USD\",\"token\":{\"token_type\":\"FDToken\",\"token_data\":{\"value\":\"1675816774690026\"}},\"bank_resp_code\":\"100\",\"bank_message\":\"Approved\",\"gateway_resp_code\":\"00\",\"gateway_message\":\"Transaction Normal\",\"retrieval_ref_no\":\"231207\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "RVQxOTUxNjY7MTAxMjM4MTk2NzM=",
        "approvalCode": "00",
        "providerTransactionCode": "10123819673",
        "approved": true
    },
    "referenceNumber": "23120716351276103735",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "201"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"correlation_id\":\"29.0198794344561\",\"transaction_status\":\"approved\",\"validation_status\":\"success\",\"transaction_type\":\"refund\",\"transaction_id\":\"RETURN\",\"transaction_tag\":\"10123819420\",\"method\":\"credit_card\",\"amount\":\"500\",\"currency\":\"USD\",\"token\":{\"token_type\":\"FDToken\",\"token_data\":{\"value\":\"1403195903860026\"}},\"bank_resp_code\":\"100\",\"bank_message\":\"Approved\",\"gateway_resp_code\":\"00\",\"gateway_message\":\"Transaction Normal\",\"retrieval_ref_no\":\"231207\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "UkVUVVJOOzEwMTIzODE5NDIw",
        "approvalCode": "00",
        "providerTransactionCode": "10123819420",
        "approved": true
    },
    "referenceNumber": "23120716254237936302",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "201"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"correlation_id\":\"29.0198853448283\",\"transaction_status\":\"approved\",\"validation_status\":\"success\",\"transaction_type\":\"void\",\"transaction_id\":\"ET183614\",\"transaction_tag\":\"10123819684\",\"method\":\"credit_card\",\"amount\":\"500\",\"currency\":\"USD\",\"token\":{\"token_type\":\"FDToken\",\"token_data\":{\"value\":\"1675816774690026\"}},\"bank_resp_code\":\"100\",\"bank_message\":\"Approved\",\"gateway_resp_code\":\"00\",\"gateway_message\":\"Transaction Normal\",\"retrieval_ref_no\":\"231207\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "RVQxODM2MTQ7MTAxMjM4MTk2ODQ=",
        "approvalCode": "00",
        "providerTransactionCode": "10123819684",
        "approved": true
    },
    "referenceNumber": "23120716353342204723",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "201"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"correlation_id\":\"29.0204931849798\",\"Error\":{\"messages\":[{\"code\":\"invalid_exp_date\",\"description\":\"Expiry Date is invalid\"}]},\"transaction_status\":\"Not Processed\",\"validation_status\":\"failed\",\"transaction_type\":\"authorize\",\"method\":\"credit_card\",\"amount\":\"500\",\"currency\":\"USD\"}",
        "gatewayErrors": [
            {
                "code": "invalid_exp_date",
                "message": "Expiry Date is invalid"
            }
        ],
        "tokenExTransactionCode": "",
        "approved": false
    },
    "referenceNumber": "23120809283797202634",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "400"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"correlation_id\":\"29.0204997928276\",\"transaction_status\":\"declined\",\"validation_status\":\"success\",\"transaction_type\":\"authorize\",\"transaction_tag\":\"10123882445\",\"method\":\"credit_card\",\"amount\":\"530300\",\"currency\":\"USD\",\"avs\":\"1\",\"cvv2\":\"I\",\"token\":{\"token_type\":\"FDToken\",\"token_data\":{\"value\":\"7116870975131111\"}},\"card\":{\"type\":\"Visa\",\"cardholder_name\":\"Frank Walter\",\"card_number\":\"1111\",\"exp_date\":\"0725\"},\"bank_resp_code\":\"303\",\"bank_message\":\"Processor Decline\",\"gateway_resp_code\":\"00\",\"gateway_message\":\"Transaction Normal\",\"retrieval_ref_no\":\"231208\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "",
        "approvalCode": "00",
        "providerTransactionCode": "10123882445",
        "approved": false
    },
    "referenceNumber": "23120809393711524461",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "201"
}

Overview

Supported Request Parameters

📘To indicate a transaction is recurring

Example Requests

Gateway Response Parameters

Example Responses

📘
To indicate a transaction is recurring