Payeezy

Follow the standard PaymentsOS integration procedure, and then apply the relevant extra specifications in this section to integrate with Payeezy.

API Version

Minimum required API version: 1.2.0

The following features require an API version higher than the minimum:

  • 3DS 2.0 External requires API version 1.3.0

Payment Methods

The following table lists all supported payment methods.

Payment MethodPayment Method Type
American ExpressCards
Apple Pay - Encrypted TokeneWallet
DINERSCards
DISCOVERCards
JCBCards
MASTERCARDCards
VISACards

Currencies

See Payeezy Currencies.

Features

The following table provides an overview of all supported and non-supported features.

FeatureSupported
3DS 1.0 ExternalYes
3DS 1.0 InternalNo
3DS 2.0 ExternalYes
3DS 2.0 InternalNo
InstallmentsNo
Level 2 and 3 DataNo
Multi-seller PaymentsNo
Network TokensNo
Payment FacilitatorNo
PayU RiskNo
Pre-authorizationNo
Retrieve Supported Payment MethodsNo
Retrieve Supported PlansNo
Statement Soft DescriptorYes
Stored Credentials FlagYes
Transaction Processing without CVVYes

Requests

The following table lists all supported requests for card-based transactions. Use the bodybuilder to create a sample request body for each request type.

Supported requests for card transactions.
RequestPartial/MultipleMode
AuthorizePartial and multiple are not supportedSynchronous
Capture Both partial and multiple are supportedSynchronous
Charge Not ApplicableSynchronous
Refund Both partial and multiple are supportedSynchronous
Void Not ApplicableSynchronous
Supported requests for eWallet transactions.
RequestPartial/MultipleMode
ChargePartial and multiple are not supportedAsynchronous

Request Retries in the Event of a Provider Network Error

Since requests with Payeezy are not idempotent safe, we cannot deduce the status of a request in the event of a provider_network_error. We will therefore return a 201 status code and keep the request in status Pending to prevent double-charges. You can now choose to Void the transaction. If the Void is successful, then you can retry the request. Beware that retrying the request without successfully voiding the transaction, may result in a double-charge. If the Void failed, please contact Zooz or Payeezy support for assistance.

Setup Procedures

The following table lists the setup procedures that are specific to this provider.

ConfigurationRequired/Optional
In the PaymentsOS Control Center, configure the following credentials:
  • Merchant token
  • API Key
  • API Secret
To obtain your credentials, complete the setup procedures with Payeezy.
Required

Integration Procedures

The following sections list the integration procedures that are specific to this provider.

Integrating Apple Pay

Integrating Apple Pay involves the following:

  • Configuring your Apple Developer Account and adding Apple Pay to your checkout page.

  • Integrating Apple Pay with your PaymentsOS transaction flows.

Configuring your Apple Developer Account

Before following the procedures below, contact us to request a CSR (Certificate Signing Request) certificate. Apple requires this certificate. Then proceed as follows:

  1. Configure your Apple Developer Account for Apple Pay. For help, see this video on the Apple developer site. Note that you will be required to upload the CSR (Certificate Signing Request) certificate as part of the configuration procedures.

  2. When setting up your account in step 1, you will generate a apple_pay.cer file. Send us this file so that we can store it in your account.

  3. Integrate Apple Pay in your checkout page using Apple’s Javascript API, as explained on the Apple developer site.

Now proceed to integrate Apple Pay with PaymentsOS.

Integrating Apple Pay with PaymentsOS

Once your Apple Developer account is setup and you’ve added Apple Pay to your checkout page, you are ready to integrate Apple Pay with PaymentsOS.

When the customer chooses to pay with Apple Pay, Apple will return a token to your web page. Here’s a sample token:

{
  "version": "EC_v1",
  "data": "DjI8Ez7nPhVo742aGEzABz/TfxCPt9LSdf2/h+0xIgVJbi3fQqd4lv3ogoTI3SQ7vZrDAWI8g2lbd5sflXBHc0z+wSeybsCcqZB3n1edRFXU7+6DYmdhFFWWCejwUc6XZWmsSaVNEQf+Kc0SeYrj8Eskdapj8bYX/QXxXSPqS4IKSjB+f3O0gUXSq7LK/jA9dl+BbWW0l3gXERU6n5rcYndO5rnjiwNUpnm7EMIMfNU+IPbsubpL82kbL2MdMJB1grel03J4JKld6G0pFSmjR2mF/xBY/yKkADRhoQkVlDRicuKVMpdRXXbIQjw/yRkLv/u8iy1wXI5YmEBB+W4QpPYsuxys94gMPaKhcaEK/OaT099aFrNBezbuLMTcTzbhXOpPwWn9pkAK0eZNOQ==",
  "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCCA4ugAwIBAgIIaGD2mdnMpw8wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE2MDYwMzE4MTY0MFoXDTIxMDYwMjE4MTY0MFowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMAwGA1UdEwEB...",
  "header": {
    "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEZMzlWOx8Xo8pXlOvzYONy+gvUy59ZOeuCov3kzc7fESczZTyvmA9dU9AdVMFaYyfCXlMG5oedi3Wy4yubqfxtg==",
    "publicKeyHash": "xrJqUFO2jN5edGS8iETkfNXtwqnwSqRUUrQJBysFpZ8=",
    "transactionId": "aa0b77fbb4f64cd3e5deef65177938b2d836e0d7d93d58000d8d54cfca19ae13",
    "merchantIdentifier": "QQO004.XYZ",
  }
}

Once you’ve obtained a network token through Apple Pay, the payload needs to be passed ‘as is’ (that is, without decryption), after which we extract the network token for you. You pass the token fields as key-value pairs under payment_method.additional_details in the Create Charge request. Make sure to also include all fields from the token header object using key names as shown in the example below (include just the fields, not the entire object). Optionally, you can also include an applicationData field and applicationDataHash field (applicationDataHash is required if you pass applicationData).

Here’s a sample request body:

{
  "payment_method": {
    "source_type": "ewallet",
    "type": "untokenized",
    "vendor": "applepay",
    "additional_details": {
      "data": "DjI8Ez7nPhVo742aGEzABz/TfxCPt9LSdf2/h+0xIgVJbi3fQqd4lv3ogoTI3SQ7vZrDAWI8g2lbd5sflXBHc0z+wSeybsCcqZB3n1edRFXU7+6DYmdhFFWWCejwUc6XZWmsSaVNEQf+Kc0SeYrj8Eskdapj8bYX/QXxXSPqS4IKSjB+f3O0gUXSq7LK/jA9dl+BbWW0l3gXERU6n5rcYndO5rnji...",
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEZMzlWOx8Xo8pXl...",
      "publicKeyHash": "xrJqUFO2jN5edGS8iETkfNXtwqnwSqRUUrQJBysFpZ8=",
      "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5j...",
      "transactionId": "aa0b77fbb4f64cd3e5deef65177938b2d836e0d7d93d58000d8d54cfca19ae13",
      "version": "EC_v1",
      "merchantIdentifier": "QQO004.XYZ",
      "applicationData": "VEVTVA==",
      "applicationDataHash": "94ee0593..."
    }
  }
}

Of course, you can use the BodyBuilder to generate sample requests (make sure to choose the eWallet payment type).

Last modified November 29, 2022