Authentication Options
To use the ANZ eGate payment gateway, you first need to authenticate using one of the following methods:
If you are using the 3D Secure (3DS) authentication for card payments with the Direct Payment integration method, your payer needs an authenticated session for their authentication interactions. The authenticated session is created using your merchant authentication, such as, password or SSL certificate.
Password authentication
To use password authentication, you need a system-generated password, which is a 16-byte randomly generated value encoded as a hex string. For instructions about generating the password, see Setting up API Credentials.
Keep your password confidential to protect your account.
If you use password authentication, you must include the Authorization header in your API requests, with the value:
Basic <base64-encoded string of “merchant.<merchant_ID>:<password>”
SSL certificate authentication
The SSL certificate authentication is also known as Client Certificate Authentication or mutual Transport Layer Security (TLS). To use this, present a certificate to authenticate yourself to the gateway. Certificates are typically issued from one of many organizations that act as Certificate Authorities (CA). This model of authentication is a component of Public Key Infrastructure (PKI) where security is achieved through confidentiality, integrity, non-repudiation, and authentication.
- The CA claims that the public key:
- Attached to the certificate is correct.
- Belongs to the person or entity claimed and it is 'authentic'.
- Is not tampered with or replaced by a malicious third party.
- SSL certificate authentication is currently not supported with Batch or Reporting APIs.
- The host name used in the API requests with certificate authentication is different than the one used with password authentication. Contact ANZ Worldline Payment Solutions for the correct host name.
- If you use SSL certificate authentication, do not include the
Authorizationheader in your API requests.
The mechanism for SSL certificate authentication requires both the client (your web server) and the server (ANZ eGate payment gateway HTTP server) to present certificates for authenticating themselves. This is termed as mutual authentication and is shown in the following figure.
Figure: SSL certificate authentication workflow
When you connect to the gateway using SSL certificate authentication, the workflow proceeds as follows:
- The client requests a connection to a protected resource on the server. This takes place for every operation request initiated by the client.
- The server presents its certificate chain to the client.
- The client verifies the server's certificate using a trust store that contains the trusted root CA. The client validates the certificate path to a trusted CA root certificate.
- If successful, the client sends its certificate chain contained in a key store to the server.
Depending on the client software, the trust store and key store are often the same.
- The server verifies the client's certificate using the full set of trusted or approved CA root certificates that are loaded on to the server. The server performs the following actions:
- Check whether the certificate is in X.509 certificate format.
- Validate the certificate path to a trusted CA root certificate.
- Perform a Certificate Revocation List (CRL) or Online Certificate Status Protocol (OCSP) check to ensure the certificate is not revoked.
- Check whether the certificate has expired.
Once the server has successfully validated the client certificate, the full client certificate chain is passed on to the API for verification. If not, then the server returns the standard SSL certificate error messages.
Verification occurs at both the server and API levels. The server performs full SSL certificate validation and the API performs business-level certificate authentication. - The API performs the following actions:
- Extracts the subject common name of the client certificate and confirms that it matches the subject common name recorded against the merchant in the database. The subject common name of the certificate must contain the legal business name of the merchant.
- Verifies that the client certificate has a Key-Usage extension and is marked critical, which includes client authentication as a permissible use of the certificate.
- Performs a simple validation of the client certificate against a CA root certificate contained in the set of allowed CA. This means the API application must hold the CA's root certificate that was used to issue and sign the client certificate.
ANZ Worldline Payment Solutions determines the initial set of allowable CA.
- Checks whether the presented certificate matches with the status of the merchant profile. A production profile only accepts production certificates whereas a test profile accepts either test or production certificates.
If steps "a" to "d" are successful, the merchant authentication is deemed successful, otherwise the connection is rejected with an appropriate error message.
- If all the actions outlined in steps 5 and 6 are successful, the server accepts the connection and allows the operation request to proceed.
You can choose to present your client certificate or a different certificate to authenticate yourself when the payer accesses your application. In this interaction, your web server acts as a server and the payer as a client. Integrating with this authentication mechanism can give your payers the added assurance that they are transacting with a legitimate enterprise.
Comparison of authentication options
The following table outlines the key differences between the password and SSL certificate authentication options. Use them to select the option that best meets your business requirements.
| Password | SSL Certificate | |
|---|---|---|
| When to use | With small businesses where simple authentication meets the requirements. | With large enterprises where the cost of implementing PKI is minimal against the security gained using a higher level of authentication. |
| Technical skills required | Requires knowledge of basic HTTP authentication. | Requires knowledge of mutual authentication and PKI using CA. |
| Ease of integration | Easy to integrate | Relatively complex due to the need to set up the keystore file and other infrastructure. |
| Level of authentication | Moderate | High |
| Cost | Least expensive | Involves additional costs, such as, the certifying authority's subscription cost for issuing the SSL certificates. |
| Benefits | Ideal for smaller merchants where the cost of integration is an important factor and business models do not require higher security levels. | SSL mutual authentication provides very high security and is considered an industry best practice. It optimizes authentication performance by using the existing SSL connection, which is typically created anyway. The extra overhead of sending the client certificate is minimal. |
| Disadvantages | Password is embedded as clear text in the HTTP authentication header and must be sent over SSL. ANZ eGate payment gateway protects the password from disclosure by only accepting SSL-protected connections. However, you must perform proper server authentication to prevent accidental disclosure to rogue servers. |
None |
| Support for sharing credentials across multiple merchant profiles | Passwords can not be shared across multiple merchant profiles. | Allows you to share a certificate set ID with multiple merchant profiles within and across ANZ Worldline Payment Solutions based on your merchant profile configuration created by ANZ Worldline Payment Solutions. |
Session authentication
Session authentication uses a Payment Session, a temporary container for request fields to authenticate the merchant. An authenticated merchant creates the payment session using the password or SSL certificate authentication, so the payer can use it for gateway interactions such as performing authentication operations.
The session authentication is only available from the API v55 onwards.
The session authentication mechanism allows the payers to provide their payment details directly to the gateway. The payer data is obtained through a client-side interaction with the gateway, either through the payer's browser or an app on the payer's mobile device. The mechanism provides a simple integration model to securely obtain the required payer data, as the API requests to the gateway are performed directly from the client rather than from your server.
To use session authentication type:
- Create a session by submitting the API Create Session request from your server to the gateway server. This operation returns a session ID.
- Submit a follow-up API request using session authentication.
The session authentication uses basic HTTP authentication mechanism similar to password authentication, where you include the authorization header in the request with the following value:Basic <base64-encoded string of “merchant.<merchant_ID>:<session_ID>”>- The follow-up request are of two types:
- The API Update Session request
- The Payer Authentication API Initiate Authentication or Authenticate Payer request.
- Provide the session to the payer.
In session-authenticated interactions with the gateway, the payer is restricted to a subset of fields within an API operation. For more information about the supported payer input and output fields, see Session Authentication Fields.