Certegy Ezi-Pay Gateway Reference
Communicating with Certegy Ezi-Pay in order to process a transaction via our payment gateway involves the customers' browser issuing an HTTP POST request to the Certegy Ezi-Pay gateway. This can be viewed as an authorisation request that is performed by the shopping cart in order to process the payment via Certegy Ezi-Pay.
There are two Certegy Ezi-Pay gateways that transaction information can be posted to and they represent the live Certegy Ezi-Pay payment gateway and the test (sandbox) gateway.
Certegy Ezi-Pay Gateways
Posting a request to the live payment gateway with the x_test set to false will process a real transaction. This means the credit card that was used as part of the checkout process will be debited. On the other hand, posting to the test gateway simulates a transaction and is not processed as a real transaction; that is, no real dollar amount will be debited from the specified credit card.
To test Certegy Ezi-Pay, you can use the test (sandbox) URL or you can use the live payment gateway with the testing flag enabled x_test = true.
Test transactions will not incur any debits, and any credit card details will not be stored.
| Certegy Ezi-Pay Environment | URL |
|---|---|
| Production Gateway | https://secure.certegyezipay.co.nz/Checkout?platform=Default |
| Sandbox Gateway | https://securesandbox.certegyezipay.co.nz/Checkout?platform=Default |
Request POST
Posting to the Certegy Ezi-Pay gateway, regardless of whether this is done in the live or test environment, should be done using the format application/x-www-form-urlencoded. Please note that Certegy Ezi-Pay adopts the convention of prefixing the various key names with x_ .
Below is an overview of the various key-value pairs that can be passed to Certegy Ezi-Pay (Request Values), a description of what they are as well as an indication of whether they are mandatory or optional.
Request values
| Key | Description | Type | Example |
|---|---|---|---|
| x_account_id Required | This is a unique Merchant ID that is assigned by Certegy Ezi-Pay to individual merchants | unicode string | 123456 |
| x_amount Required | Represents the transaction's total amount including any taxes and shipping costs | decimal | 99.90 |
| x_currency Required | Currency of the transaction | ISO-4217 | NZD |
| x_customer_billing_address1 | Billing address line 1 | unicode string | 120 Albert Street |
| x_customer_billing_address2 | Billing address line 2 | unicode string | Level 14 |
| x_customer_billing_city | Billing city | unicode string | Auckland |
| x_customer_billing_country | Billing country | iso-3166-1 alpha-2 | NZ |
| x_customer_billing_state | Billing state | unicode string | Auckland |
| x_customer_billing_postcode | Billing postcode | unicode string | 1010 |
| x_customer_email | Billing email address | unicode string | user@example.com |
| x_customer_first_name | Customer's first name | unicode string | John |
| x_customer_last_name | Customer's last name | unicode string | Appleseed |
| x_customer_phone | Customer's phone number | unicode string | 0800 444 827 |
| x_customer_shipping_address1 | Shipping address line 1 | unicode string | 120 Albert Street |
| x_customer_shipping_address2 | Shipping address line 2 | unicode string | Level 14 |
| x_customer_shipping_city | Shipping city | unicode string | Auckland |
| x_customer_shipping_country | Shipping country | unicode string | NZ |
| x_customer_shipping_first_name | Customer's first name (Shipping) | unicode string | John |
| x_customer_shipping_last_name | Customer's last name (Shipping) | unicode string | Appleseed |
| x_customer_shipping_phone | Customer's phone number (Shipping) | unicode string | 0800 444 827 |
| x_customer_shipping_state | Shipping state | unicode string | Auckland |
| x_customer_shipping_postcode | Shipping postcode | unicode string | 1010 |
| x_description | Item's description as setup in the shopping cart | unicode string | Order #767 |
| x_reference Required | A reference that uniquely references the order and assigned by the merchant. This is unique to the shopping cart. | ascii string (max length 36 bytes) | 19783 |
| x_shop_country Required | Country of where the merchant's store is located | iso-3166-1alpha-2 | NZ |
| x_shop_name Required | Store name as advertised on the internet, TV and other media | Shop Inc | |
| x_signature Required | Request payload that is signed/verified using HMAC-SHA256 | hex string, case-insensitive | See Signature Generation |
| x_test Required | Indicates whether the transaction is to be processed using the live or test Certegy Ezi-Pay gateway | true/false | true |
| x_url_callback Required | Callback notifications are sent asynchronously to this URL | URL | https://shop.co.nz/callback |
| x_url_cancel Required | Customers are redirected to this URL if they want to quit their Certegy Ezi-Pay transaction and return to the shopping cart store instead | URL | https://shop.co.nz/cancel |
| x_url_complete Required | Customers are redirected to this URL if they have successfully processed their transaction using Certegy Ezi-Pay | URL | https://shop.co.nz/compete |
Sample POST
Below is a sample request that might be posted to an Certegy Ezi-Pay gateway that is in the application/x-www-form-urlencoded format. In this example, please ignore values for individual keys - such as the value for x_signature - since this sample POST is for demonstration purposes only and does not demonstrate a real transaction that can be completed by Certegy Ezi-Pay.
POST and GET responses
There are two responses from Certegy Ezi-Pay.
The first response that Certegy Ezi-Pay always performs is a server-to-server asynchronous POST to the shopping cart on the gateway specified in the x_url_callback and in the format application/x-www-form-urlencoded. Similar to the request POST, the response POST includes key-values pairs that are specific to that transaction and indicate things such as the outcome of that particular transaction if it has failed or is completed successfully for instance.
The second response is a HTTP GET to the client on either of the URLs specified in x_url_complete or x_url_cancel.
Response POST values
Below is an overview of the various response key-value pairs that Certegy Ezi-Pay returns after it has finished processing a transaction. Note that some of these key-value pairs echo corresponding key-value pairs in the request that Certegy Ezi-Pay receives - as is the case with x_currency for instance.
| Key | Description | Type | Example |
|---|---|---|---|
| x_account_id | This is the Merchant ID assigned by Certegy Ezi-Pay to the merchant | unicode string | 123456 |
| x_reference | A reference that uniquely references the order and assigned by the merchant | ascii string | 19783 |
| x_currency | Currency of the transaction | ISO-4217 | NZD |
| x_test | Indicates whether the transaction is to be processed as a live or a test transaction | True/False | False |
| x_amount | Represents the transaction's total amount including any taxes and shipping costs | decimal | 99.90 |
| x_gateway_reference | A reference for the authorisation issues by Certegy Ezi-Pay that is unique | unique string | 123 |
| x_timestamp | Time at which the transaction is completed, in UTC format YYYY-MM-DDTHH:MM:SSZ | iso-8601 in UTC | 2017-06-24T12:11:43Z |
| x_result | Values that represent the outcome of a transaction | Valid values are completed or failed | completed |
| x_signature | Response payload that is signed/verified using HMAC-SHA256 | hex string, case-insensitive | See Signature Generation |
Response POST reply
It is expected that the POST reponse will be replied to by the sellers server to confirm that the POST response was recieved.
The expected key-value pairs of this reply are listed below.
| Key | Description | Type | Example |
|---|---|---|---|
| x_reference | A reference that uniquely references the order and assigned by the merchant | ascii string | 19783 |
| x_result | Values that represent the outcome of a transaction | Valid values are completed or failed | completed |