Getting Started with Payeezy

Using below listed steps, you can easily integrate your mobile/web payment application with Payeezy APIs And go LIVE!

• LITE - REGISTRATION
• CREATE AN API
• BUILD AND TEST YOUR INTEGRATION
• GET CERTIFIED
• ADD MERCHANTS
• GO LIVE!

LITE Registration

Sign up for a free developer account with LITE Registration. All you need is your First name, Last name and a valid email address. Navigate to developer portal https://developer.payeezy.com/ from your browser and click on CREATE ACCOUNT. c Note: Portal registration requires a valid e-mail address. Once registered, your email address cannot be changed in future. All e-mails from the system will be sent to this registered email address. The e-mail address will not be made public and will only be used if you wish to receive notifications by e-mail. After you provide registration information an email is sent to you with further instructions to activate your account.

CREATE AN API

Think of this as a unique app name that is used to identify your application. This is unrelated to the name you would use on Apple’s App Store (if you are integrating with apple pay/iOS) but it can be the same.

• Login to your Payeezy developer account and navigate to the "APIs" page.
• Click the “+ ADD A NEW API” button.
• On the next screen you name your application. If the API is only for testing, choose "Sandbox". If you plan to use the API in the production environment, choose "Live" as well.
• Click on the API you just created. You will see your API key and API secret. These are header parameter values that uniquely identify your transactions associated with all API calls.

BUILD AND TEST YOUR INTEGRATION

We provide a free testing environment to test your app in the SANDBOX region. To integrate and test your application all you need is

• Merchant token
• API Key
• API Secret
• JS_Security_Key (Only required for when using the tokenization API)
• TA_TOKEN (Only required For US domiciled merchants when using the tokenization API)
• CSR or public key (only required for mobile wallet integration)

The Merchant token and JS_Security_key are available from the "Merchants" page in your developer account. These values are unique for each merchant. For testing, we have made available a First Data owned demo US gateway account called "Acme Sock". You may choose to use this or connect to your own US demo account or non-US demo account by clicking on the "Add a demo account" button. Follow the instructions on how to add your demo account or how to sign up for a demo account. Once you add your demo account, you should see it listed in the Merchants list under "Sandbox" and you should also see the merchant token and js_security_key pertaining to that account.

The TA_TOKEN is "NOIW" for the sandbox merchant. For live processing, the TA_TOKEN will be available from Payeezy Gateway terminal. The API key and API secret are created by you and are available in the "APIs" page. The CSR or public key are created by you and are available in the "CERTS" page.

Select one of the Payeezy integration methods available from Integrations page

To test and integrate your payment application with Payeezy CERT environment use following URL: https://api-cert.payeezy.com/v1/.

Get Certified (Developer’s certification)

In order to add Merchants and Go-Live with Payeezy, you need to get certified as a Payeezy Certified Developer. Certification involves: 1. Completing a full registration 2. Submitting a sample payload as a valid JSON Purchase transaction in SANDBOX region.

JSON request will be tested against Payeezy Cert/Sandbox environment. After you click on the certify button, JSON response and response message will be provided below certify button.

You will be certified after submitting the CERTIFICATION form.

Add Merchant(s)

Once your certification is complete, developer portal will automatically redirect to “Add Merchant” page. Click on "Live" and then click on "Add a merchant".

• If you are adding a merchant who already has a merchant account with First Data, select "Add your existing merchant account" and follow the instructions on the screen. In order for this to work, the First Data merchant account must be enabled for Payeezy API. If you are not sure what this is, check with the merchant service provider.
• If the merchant does not have a First Data merchant account and needs to apply for one, select "Sign up for a merchant account" and follow the instructions.

If for any reason, you are unable to add your merchant account, email payeezyboarding@firstdata.com with the Merchant ID (or storeID), DBA name and developer account email address. We will add the merchant account to your developer account manually within 2 business days and send you a notification.

GO LIVE!

• Replace Sandbox URL with live environment URL: https://api.payeezy.com/v1/transactions
• Replace Sandbox merchant token with live merchant token.
• Replace Sandbox JS_Security_key with live JS_Security_key.
• Ensure that API key and API secret are enabled for live processing.
• Replace TA_TOKEN (if used) with the live TA_TOKEN available in Payeezy Gateway terminal
• Use live certificates for mobile wallet integrations.

When you process any transaction using the original credit card number, the Payeezy system is able to determine the card type programmatically, based on the length of the number and the first digit and override the provided card type, if necessary.

However, when you use a token number instead of a card number, the first digit of a token number is random and so the system has no way to programmatically determine the card type, so the card type you provide is trusted. In this case, if an incorrect card type is provided, then the transaction gets declined.

One of the biggest benefits of using our APIs is that once an integration is built, both US merchants and non-US merchants can use it. There are, however, 2 important differences to note when developing for US merchants vs Non-US merchants.

1. When using the GET Token API (/securitytokens), US merchants will need to send the TA_TOKEN parameter while non-US merchants will need to send the "Currency" parameter.

2. For a non-US merchant, the parameter “merchant_ref” should be unique for each transaction. It is not required for US merchants but is definitely recommended for ease of reconciliation.

3. In token based transactions, for non-US merchants, CVV is required. It is not required for US merchants.

Once the above caveats are handled in your integration, it should be usable by US merchants as well as Non-US merchants.

For US demo merchant accounts
There are a number of ways to generate unsuccessful transactions from a demo account.

Simulate unapproved Bank Responses
You can use the dollar amounts between 5000.00 - 5999.00 to trigger a variety of Bank Responses, where the desired response code is added to 5000.

Simulate unsuccessful Ecommerce Responses
You can use the penny amounts to trigger a variety of eCommerce Responses, where the desired response code is added to 5000.00.
For example, to simulate a transaction that encountered the "Unable to Send Trans" error (code 42) during processing, use 5000.42 as the transaction amount.

Note: If both the dollar and penny amounts would trigger a simulated code (for example, 5200.42), the penny amount trigger will take precedence.

A CSR or a public key is required only if you are planning on processing payments through any of the mobile wallets (Apple Pay, Android Pay, etc.). If that is you, and you have already created a Payeezy account to test in our sandbox (yes, this is required to do this task), follow these simple steps:

On the Payeezy Developer Portal
1 – From wherever you are on the portal, select the ‘CERTS’ option in the top right.
2 – Here you can create your certificates for both sandbox and production environments. Creating a certificate is easy, just select the type of certificate you need, enter your app label and click "Add".
3 – Once you have created the certificate, go ahead and download it

For Apple Pay certificates
4 – Navigate to the Creating Certificates section of Apple's developer portal
5 – Follow the instructions on Apple's portal to upload the certificate from step 3.  After successful upload, you will be able to transact with Payeezy.  Refer to our SDK guide to integrate your app.

When you are using a regular credit card, our system ignores the card type sent and determines the card type based on the first digit of the card number. However, if you are using a TransArmor token instead of a card number, the system requires the card type, as the normal credit card number logic does not apply.

No. You do not need multiple certificates in order to support multiple merchants. As a developer you will need to download one certificate initially that you will register your mobile app with the wallet provider. When you add merchants to your developer account under the "Merchants" tab, a corresponding merchant token will be generated and linked to your app. You can use your certificate for any of the merchants in your "Merchants" tab. 

Note- All merchants need to have an acquiring relationship with First Data.

A token is related only to the  card number. The anatomy of a token doesn’t have any dependency on CVV, Exp date. If the card is expired the token still remains valid assuming that the new card that has been delivered to the consumer by the issuing bank has the same card number. If the card has been lost or stolen or has been cancelled by the issuing bank/consumer for any reason then the new card will have new number. In this scenario you have to re tokenize the card because the card number changed and it is entirely a new card.

If you want, you can delete the token from your data base at your end. Once the card is tokenized with Payeezy there is no need to update the exp date as long as the new card delivered has the same card number. If the card number changes ….well it is a new card and has to be tokenized again.

This error message is usually caused when invalid data is passed to the API. Cross check the data you are passing with the sample data shown in the sandbox API pages. 

• Check for spelling errors
• Check for completeness of the message body, make sure to include all the required key-value pairs

Usually, this happens when the API credentials or Merchant token or js_security_key is incorrect:

• When testing in CERT environment
  • Ensure that you are accessing the sandbox URL - https://api-cert.payeezy.com/v1/
  • Ensure that the API is enabled for sandbox environment. Do this by going to My APIs and edit your API.
  • Ensure that you are using the merchant token listed in the "My Merchants" page under the "Sandbox" tab.
  • In tokenization requests, if applicable, ensure that you are using ta_token = 'NOIW'
  • If you have added your own demo account via the Merchants tab, verify that the HMAC key and gateway password are accurately entered. (You can update this, if required, by re-adding your demo account)
• In PROD environment,
  • Ensure that you are accessing the production URL - https://api.payeezy.com/v1/
  • Ensure that the API is enabled for Live environment. Do this by going to My APIs and edit your API.​
  • If you have added your merchant account using the "Add merchant" form, make sure that the HMAC key and Gateway password are accurately entered. (You can update this, if required, by re-adding your merchant account)
  • Ensure that you are using the merchant token listed in the "My Merchants" page under the Live tab.

1. Ensure that the values of API key, API secret, token, timestamp, nonce and data used in calculating HMAC match the corresponding values used in the HTTP headers.
2. Ensure that the correct hashing algorithm is used.
3. Ensure that the API key, API secret and merchant token are correctly entered without leading or trailing spaces.
4. Ensure that the timestamp in the HTTP headers is in milliseconds and represents epoch time calculated from UTC time.
5. Ensure that the timestamp in the HTTP header is within 5 minutes of our server time. This depends on your server time.

Sample code for generating HMAC is available in the "Docs and Sandbox" page and in Direct API repositories

If you want to process tokenized payments using multi-pay tokens, your account needs to be enabled with the appropriate service (TransArmor or Data Vault). Contact your merchant account representative or contact us for TransArmor/Data Vault enablement.

When you interface with the Payeezy.JS integration method, you never touch or save consumer’s credit card details. This diminishes the PCI burden on your end reducing your infrastructure costs, audit risks and many undesirable things while giving you complete control of check out process.

The process involves your web infrastructure serving up payment pages that fully control the checkout process.  Once the consumer is ready to check out, has entered and confirmed their credit card information, and has hit the “pay” button, a Payeezy.js <script> tag included on the page intercepts the form and asynchronously posts the credit card details to our servers.

This call uses JSONP over https passing in a unique API key and identifier. Upon either authorization approval or a straight GetToken method, we will return a token and Payeezy.js will save the token information (instead of CC details) in a hidden form field on the checkout page and submit it your server. Your server will then submit the token to Payeezy to complete the transaction using the appropriate server side library via an API call using HMAC authentication over HTTPS.

Bottom line? This is the simplest, most secure and most flexible way to integrate your checkout pages with our payment capabilities.

Here’s why:

• You’ll have complete control over the look and feel of your checkout and payment pages as well as the entire checkout process. 
• Throughout the entire process, you’ll never touch consumers’ credit card data.
• Interactions with our servers are highly secured, preventing “man in the middle” attacks.
• Consumers’ card data is tokenized, providing further protection of credit card data during the transaction.

A CSR or a public key is required only if you are planning on processing payments through any of the mobile wallets (Apple Pay, Android Pay, etc.). If that is you, and you have already created a Payeezy account to test in our sandbox (yes, this is required to do this task), follow these simple steps:

On the Payeezy Developer Portal
1 – From wherever you are on the portal, select the ‘CERTS’ option in the top right.
2 – Here you can create your certificates for both sandbox and production environments. Creating a certificate is easy, just select the type of certificate you need, enter your app label and click "Add".
3 – Once you have created the certificate, go ahead and download it

For Apple Pay certificates
4 – Navigate to the Creating Certificates section of Apple's developer portal
5 – Follow the instructions on Apple's portal to upload the certificate from step 3.  After successful upload, you will be able to transact with Payeezy.  Refer to our SDK guide to integrate your app.