Skip to main content

Gateway Integration Library

A simple server-side integration library is available to simplify the preparation and transmission of Hosted and Direct Integration requests.

The library is available in many popular programming languages and is based around a single class: the Gateway class.

The Gateway integration library does not currently support the preparation and transmission of Batch Integration requests.

Library Namespace​

To avoid polluting the global namespace, the library uses the ‘P3/SDK’ namespace where supported by the language.

Gateway Configuration​

Before you can use the Gateway class, you will need to configure the following properties to match your integration parameters explained in the Prerequisites section and authentication parameters detailed in Authentication section.

Property NameTypeDescription
hostedURLstringAbsolute URL provided for the Hosted Integration.
directURLstringAbsolute URL provided for the Direct Integration.
merchantIDstringYour unique Merchant ID to be passed in the merchantID integration field.
merchantPwdstringAny password configured on your Merchant Account as per the Password Authentication section.
merchantSecretstringAny secret configured on your Merchant Account as per the Message Signing section.
proxyUrlstringAbsolute URL to any proxy required for connections. (eg https://www.proxy.com:3128)
debugbooleanTrue to enable debugging output.

Gateway Methods​

The follow methods are made available by the Gateway class:

string hostedRequest(mixed[] request, string[] options)

Return an HTML fragment that can be included in your webpage to render a <form> which will send the provided request data to the Gateway’s Hosted Integration when submitted.

The request parameter should be an associative array containing the request fields required to be sent. The request fields are not validated

The following class properties are used unless alternative values are provided in the request array: directUrl, merchantID, merchantPwd, merchantSecret.

The options parameter is an optional associative array containing options that can be used to modify the returned HTML fragment as follows:

· formAttrs string containing additional attributes to include in the form tag.

· submitAttrs string containing additional attributes to include in the submit button tag.

· submitImage string containing the URL to use as the submit button.

· submitHtml string containing HTML to use as the label on the submit <button>.

· submitText string containing text to use as the label on the submit <input/>.

The submitImage, submitHtml and submitText options are mutually exclusive and will be checked for in that order. If none is provided, then a submitText value of ‘Pay Now' is assumed.

If a merchantSecret is provided, then the method will add the correct signature field to the request.

An exception is thrown if the HTML fragment cannot be composed.

The verifyResponse() method can be used to validate and decode any response POSTed back to your website.

Please refer to the Hosted Sale Transaction in the Example Library Code section for an example of how to use this method.

Returns a string containing the HTML fragment if successful; throws an exception otherwise.

mixed[] directRequest(mixed[] request, string[] options)

Return the response received when sending the provided request to the Gateway’s Direct Integration.

The request parameter should be an associative array containing the request fields required to be sent. The request fields are not validated.

The following class properties are used unless alternative values are provided in the request array: directUrl, merchantID, merchantPwd, merchantSecret.

The options parameter is not used and reserved for future use.

If a merchantSecret is provided, then the method will add the correct signature field to the request and check the signature field on the response

An exception is thrown if the request cannot be sent; or the response cannot be received; or if the response’s signature is incorrect.

Please refer to the Example Library Code section for an example of how to use this method.

Returns an associative array containing the received response fields; otherwise, throws an exception.

void prepareRequest(mixed[] &request, string[] &options,string &secret, string &direct_url, string &hosted_url)

Prepare a request for sending to the Gateway’s Direct Integration.

The request parameter should be a reference to an associative array containing the request fields required to be sent. The request fields are not validated.

The merchantSecret, directUrl and hostedUrl configuration properties will be returned in the secret, direct_url and hosted_url method parameters. These properties can be overridden by providing them in the request, in which case they will be extracted and removed from the request.

The merchantID and merchantPwd configuration properties will be added to the request.

A few known Gateway response fields will be removed from the request, if present, to avoid confusion, notably the responseCode, responseMessage, responseStatus, state fields.

An exception will be thrown if the request does not contain an action element or a merchantID element (and none could be inserted).

void verifyResponse(mixed[] &response, string secret

Verify a response received from the Gateway’s Hosted or Direct Integration.

The response parameter should be a reference to an associative array containing the response received from the Gateway, either from the Direct Integration or as POSTed from the Hosted Integration.

The secret parameter should be any Merchant secret to use when checking the response’s signature element. If not provided, then the value of the merchantSecret property is used.

Any signature element is removed from the response.

An exception is thrown if the response is not valid, does not contain a responseCode element or its signature is incorrect.

Please refer to the Direct Sale Transaction (with 3-D Secure) in the Example Library Code section for an example of how to use this method.

string sign(mixed[] request, string secret, mixed partial = false)

Return the signature for the provided request data.

The request parameter should be a reference to an associative array containing the request fields required to be sent. The request fields are not validated.

The secret parameter should be the Merchant secret to use when signing the request.

The partial parameter should be either the boolean false or comma separated string; or an array of strings containing the names of the request elements to sign.

Returns a string containing the correct signature for the request.