The Client Library for Payco Advanced
PHP Client Library for the UPG API. Based on the API Documentation found here: https://www.manula.com/manuals/payco/payment-api/hostedpagesdraft/en/topic/introduction
Currently there are issues with some of the calls these are:
- CreateTransaction : The url field was renamed from the API documentation
- UpdateTransaction : Currently Incomplete
The API requires the configuration to work correctly. All classes and methods that require cofiguration can be passed a populated instance of Upg\Library\Config.
The config object should be fully populated at instantiation by providing an associative array.
$configData = array('merchantID' => 1, 'storeID' => 1); $config = new Upg\Library\Config($configData);
The fields for the config that must be provided are:
- ['merchantPassword'] string This is the merchant password for mac calculation
- ['merchantID'] string This is the merchantID assigned by UPG.
- ['storeID'] string This is the store ID of a merchant.
- ['logEnabled'] bool Should logging be enabled
- ['logLevel'] int Log level See class constants for possible values
- ['logLocationMain'] string Main log location file path
- ['logLocationRequest'] string Log location file path for API requests
- ['defaultRiskClass'] string Default risk class
- ['defaultLocale'] string Default locale (see Supported Languages)
- ['sendRequestsWithSalt'] bool Automatically add salt to requests. In live this should be set to true and not false. However, for testing this can be false. By default this will be true if not specified.
- ['baseUrl'] string Base URL of requests that should contain either https://sandbox.upgplc.com/2.0 or https://www.pay-co.net/2.0
When referencing log levels be sure to use the Psr\Log\LogLevel static constants
The Library for requests is split in three parts: Upg\Library\Request contains the request classes. Upg\Library\Request\Objects contains classes for the JSON objects that are documented in the API docs. If a request has a property that requires a JSON object please pass in the appropriately populated Upg\Library\Request\Objects class for that property.
All properties in the request and JSON objects have getters and setters. For example, to set a field called userType on
the request or object you would call
setUserType and to get it you would call
Any field in the Requests and JSON Objects that requires a Date should be passed a PHP DateTime object - even if the field only requires month and year. For fields that require only a month and year such as the validity of a payment instrument, please look at DateTime::setDate. Simply running the code like this would give you a DateTime object to populate the field
$expiryMonth = 2 $expiryYear = 2020 $date = new \DateTime(); $date->setDate($expiryYear, $expiryMonth, 1);
The serializer will serialize the date to a correctly formatted string for the request.
Any field that requires a JSON amount fields should be provided the Upg\Library\Request\Objects\Amount object. This object has three properties:
- amount: Full amount (subtotal+tax) in the lowest currency unit.
- vatAmount: The amount of VAT if available in the lowest currency unit
- vatRate: If a vatAmount is provided please provide details of the VAT rate up to 2 decimal places.
All amount values must be in the lowest currency unit (i.e. Cents, Pence, etc). So for example a 10 Euro transaction with 20% VAT would need to be populated:
- amount: 1200
- vatAmount: 200
- vatRate: 20
Once you have populated a request object with the appropriate values simply instantiate an instance of a Upg\Library\Api
class for the appropriate method call. Pass in a config object and the request you want to send. Then, calling the
sendRequest() method will send the response. Raise any exception or provide a success response.
The exceptions which can be raised are in Upg\Library\Api\Exception. For any parsed responses you will have access to an Upg\Library\Response\SuccessResponse or Upg\Library\Response\FailureResponse object. The success object is returned if no exception is thrown. The failure object is returned in Upg\Library\Api\Exception\ApiError exception.
The response object has two types of properties: Fixed properties such as the resultCode which are in every request, and Dynamic properties such as allowedPaymentMethods which are not in every request. To access a property that is Fixed or Dynamic, simply use the following:
If any response contains JSON objects or an array of objects then the library will attempt to serialize them into Upg\Library\Request\Objects classes. The properties names in responses that will be serialized are as follows:
- allowedPaymentInstruments, paymentInstruments : Array of Upg\Library\Request\Objects\PaymentInstrument
- billingAddress, shippingAddress : Upg\Library\Request\Objects\Address
- amount : Upg\Library\Request\Objects\Amount
- companyData : Upg\Library\Request\Objects\Company
- paymentInstrument : Upg\Library\Request\Objects\PaymentInstrument
- userData : Upg\Library\Request\Objects\Person
For example the response on the getUser API call contains the following properties that will be serialized to the following objects
- companyData field would be an Upg\Library\Request\Objects\Company object
- userData field would be an Upg\Library\Request\Objects\Person object
- billingAddress, shippingAddress would be Upg\Library\Request\Objects\Address objects
The MAC validation/calculation for requests and responses is handled by the library and if these fail an exception will be raised.
All variables that are not ISO values are defined in classes as constants for you to use in the request. For possible fixed field values please see the following constants:
- locale: Upg\Library\Locale\Codes
- riskClasses: Upg\Library\Risk\RiskClass
- userType: Upg\Library\User\Type
- salutation: Upg\Library\Request\Objects\Person::SALUTATIONFEMALE Upg\Library\Request\Objects\Person::SALUTATIONMALE
- companyRegisterType: Upg\Library\Request\Objects\Company
- paymentInstrumentType: Upg\Library\Request\Objects\PaymentInstrument
- issuer: Upg\Library\Request\Objects\PaymentInstrument
The library implements stubs for all the methods except for registerMerchant as at this time UPG is restricting this to authorised parties only.
For the reserve API call you may be provided a callback from the API as a POST/GET request. For this the client library implements a helper for you to use: Upg\Library\Callback\Handler.
This takes in the following for the constructor:
- $config: The config object for the integration
- $data: The data from the post\get variables which should be an associated array containing contain the following:
- merchantReference : Optional field
- message : Optional field
- $processor: An instance of an object that implements the Upg\Library\Callback\ProcessorInterface interface, which the method will invoke after validation
The processor should implement two methods:
sendData which the handler uses to pass data to the processor to use and another method called
run, which will get invoked to handle call back processing.
This processor should return a string which contains a URL where the user should be redirected to after UPG has processed the transaction.
To run the handler simply call the
run method on the object. Please note the following exceptions can be raised in which case the store must still send a URL, but respond with a non 200 HTTP result code to indicate there has been an issue. The following exceptions may be raised:
- Upg\Library\Callback\Exception\ParamNotProvided : If a required parameter is not provided
- Upg\Library\Callback\Exception\MacValidation : If there is a MAC validation issue with the callback parameters
For the MNS notification the API provides a helper class to validate MNS notification. This class is Upg\Library\Mns\Handler. It takes the following as a constructor:
- $config: The config object for the integration
- $data: The data from the post\get variables which should be an associated array of the MNS callback
- $processor: An instance of an object which implements the Upg\Library\Mns\ProcessorInterface interface which the method will invoke after validation.
The processor object should implement
sendData to get data from the handler and a
run method which executes your callback after successful validation.
The processor callback should avoid processing the request, instead it should save it to a database for asynchronous processing via a cron script.
Please note the MNS call must always return a 200 response to UPG otherwise no other MNS would be sent until a given MNS notification is accepted with a HTTP 200 response.
If you use the handler class to save a MNS to the database for later processing you can assume the MNS is perfectly valid with out checking the MAC.
If you want to contribute o the library, please note that all code should be written according to the PSR2 standard. This is very easy to set up in PHPStorm by using PHP-Codesniffer. To configure PHP-Codesniffer for PHPStorm follow these steps:
- Run the following.
composer global require 'squizlabs/php_codesniffer=*'
- In PHPStorm open the settings dialog and navigate to Languages & Framework -> PHP -> Code Sniffer
- On configuration option click the ... button and in that prompt point PHPStorm to the path of Code Sniffer
- To set the code style navigate to Editor -> Code Style -> PHP
- In the setting click on Set From and go to Predefined Style -> PSR1/PSR2
- Click on the OK button