PostFinance PHP library
This library allows you to easily implement an PostFinance integration into your project.
It provides the necessary components to complete a correct payment flow with the PostFinance platform., (*1)
Requirements:, (*2)
- PHP 5.3+
- network connection between your webserver and the PostFinance platform
As always, this is work in progress. Please feel free to fork this project and get those pull requests coming!, (*3)
Installation:
The library is PSR-4 compliant
and the simplest way to install it is via composer:, (*4)
composer require wysow/postfinance
Overview
- Create an EcommercePaymentRequest or CreateAliasRequest, containing all the info needed by PostFinance.
- Generate a form
- Submit it to PostFinance (client side)
- Receive a PaymentResponse back from PostFinance (as a HTTP Request)
Both EcommercePaymentRequest, CreateAliasRequest and PaymentResponse are authenticated by comparing the SHA sign, which is a hash of the parameters and a secret passphrase. You can create the hash using a ShaComposer., (*5)
The library also allows:
- Fetching order information via PostFinance API using DirectLinkQueryRequest
- Executing maintenance request via PostFinance API using DirectLinkMaintenanceRequest, (*6)
SHA Composers
PostFinance provides 2 methods to generate a SHA sign:, (*7)
-
"Main parameters only", (*8)
, (*9)
Implementation using this library is trivial:, (*10)
<?php
use PostFinance\ShaComposer\LegacyShaComposer;
$shaComposer = new LegacyShaComposer($passphrase);
-
"Each parameter followed by the passphrase", (*11)
, (*12)
Implementation using this library is trivial:, (*13)
<?php
use PostFinance\ShaComposer\AllParametersShaComposer;
$shaComposer = new AllParametersShaComposer($passphrase);
This library currently supports both the legacy method "Main parameters only" and the new method "Each parameter followed by the passphrase". Either can be used with SHA-1 (default), SHA-256 or SHA-512 encryption., (*14)
<?php
use PostFinance\Passphrase;
use PostFinance\Ecommerce\EcommercePaymentRequest;
use PostFinance\ShaComposer\AllParametersShaComposer;
use PostFinance\FormGenerator\SimpleFormGenerator;
$passphrase = new Passphrase('my-sha-in-passphrase-defined-in-postfinance-interface');
$shaComposer = new AllParametersShaComposer($passphrase);
$shaComposer->addParameterFilter(new ShaInParameterFilter); //optional
$ecommercePaymentRequest = new EcommercePaymentRequest($shaComposer);
// Optionally set PostFinance uri, defaults to TEST account
//$ecommercePaymentRequest->setPostFinanceUri(EcommercePaymentRequest::PRODUCTION);
// Set various params:
$ecommercePaymentRequest->setOrderid('123456');
$ecommercePaymentRequest->setAmount(150); // in cents
$ecommercePaymentRequest->setCurrency('EUR');
// ...
$ecommercePaymentRequest->validate();
$formGenerator = new SimpleFormGenerator;
$html = $formGenerator->render($ecommercePaymentRequest);
// Or use your own generator. Or pass $ecommercePaymentRequest to a view
CreateAliasRequest
<?php
use PostFinance\Passphrase;
use PostFinance\DirectLink\CreateAliasRequest;
use PostFinance\ShaComposer\AllParametersShaComposer;
use PostFinance\DirectLink\Alias;
$passphrase = new Passphrase('my-sha-in-passphrase-defined-in-postfinance-interface');
$shaComposer = new AllParametersShaComposer($passphrase);
$shaComposer->addParameterFilter(new ShaInParameterFilter); //optional
$createAliasRequest = new CreateAliasRequest($shaComposer);
// Optionally set PostFinance uri, defaults to TEST account
// $createAliasRequest->setPostFinanceUri(CreateAliasRequest::PRODUCTION);
// set required params
$createAliasRequest->setPspid('123456');
$createAliasRequest->setAccepturl('http://example.com/accept');
$createAliasRequest->setExceptionurl('http://example.com/exception');
// set optional alias, if empty, PostFinance creates one
$alias = new Alias('customer_123');
$createAliasRequest->setAlias($alias);
$createAliasRequest->validate();
// Now pass $createAliasRequest to a view to build a custom form, you have access to
// $createAliasRequest->getPostFinanceUri(), $createAliasRequest->getParameters() and $createAliasRequest->getShaSign()
// Be sure to add the required fields CN (Card holder's name), CARDNO (Card/account number), ED (Expiry date (MMYY)), CVC (Card Verification Code)
// and the SHASIGN
DirectLinkPaymentRequest
<?php
use PostFinance\DirectLink\DirectLinkPaymentRequest;
use PostFinance\Passphrase;
use PostFinance\ShaComposer\AllParametersShaComposer;
use PostFinance\DirectLink\Alias;
$passphrase = new Passphrase('my-sha-in-passphrase-defined-in-postfinance-interface');
$shaComposer = new AllParametersShaComposer($passphrase);
$shaComposer->addParameterFilter(new ShaInParameterFilter); //optional
$directLinkRequest = new DirectLinkPaymentRequest($shaComposer);
$directLinkRequest->setOrderid('order_1234');
$alias = new Alias('customer_123');
$directLinkRequest->setAlias($alias);
$directLinkRequest->setPspid('123456');
$directLinkRequest->setUserId('postfinance-api-user');
$directLinkRequest->setPassword('postfinance-api-password');
$directLinkRequest->setAmount(100);
$directLinkRequest->setCurrency('EUR');
$directLinkRequest->validate();
// now create a url to be posted to PostFinance
// you have access to $directLinkRequest->toArray(), $directLinkRequest->getPostFinanceUri() and directLinkRequest->getShaSign()
DirectLinkQueryRequest
<?php
use PostFinance\DirectLink\DirectLinkQueryRequest;
use PostFinance\Passphrase;
use PostFinance\ShaComposer\AllParametersShaComposer;
use PostFinance\DirectLink\Alias;
$passphrase = new Passphrase('my-sha-in-passphrase-defined-in-postfinance-interface');
$shaComposer = new AllParametersShaComposer($passphrase);
$shaComposer->addParameterFilter(new ShaInParameterFilter); //optional
$directLinkRequest = new DirectLinkQueryRequest($shaComposer);
$directLinkRequest->setPspid('123456');
$directLinkRequest->setUserId('postfinance-api-user');
$directLinkRequest->setPassword('postfinance-api-password');
$directLinkRequest->setPayId('order_1234');
$directLinkRequest->validate();
// now create a url to be posted to PostFinance
// you have access to $directLinkRequest->toArray(), $directLinkRequest->getPostFinanceUri() and directLinkRequest->getShaSign()
DirectLinkQueryRequest
<?php
use PostFinance\DirectLink\DirectLinkQueryRequest;
use PostFinance\Passphrase;
use PostFinance\ShaComposer\AllParametersShaComposer;
use PostFinance\DirectLink\Alias;
$passphrase = new Passphrase('my-sha-in-passphrase-defined-in-postfinance-interface');
$shaComposer = new AllParametersShaComposer($passphrase);
$shaComposer->addParameterFilter(new ShaInParameterFilter); //optional
$directLinkRequest = new DirectLinkQueryRequest($shaComposer);
$directLinkRequest->setPspid('123456');
$directLinkRequest->setUserId('postfinance-api-user');
$directLinkRequest->setPassword('postfinance-api-password');
$directLinkRequest->setPayId('order_1234');
$directLinkRequest->validate();
// now create a url to be posted to PostFinance
// you have access to $directLinkRequest->toArray(), $directLinkRequest->getPostFinanceUri() and directLinkRequest->getShaSign()
DirectLinkMaintenanceRequest
<?php
use PostFinance\DirectLink\DirectLinkMaintenanceRequest;
use PostFinance\Passphrase;
use PostFinance\ShaComposer\AllParametersShaComposer;
use PostFinance\DirectLink\Alias;
$passphrase = new Passphrase('my-sha-in-passphrase-defined-in-postfinance-interface');
$shaComposer = new AllParametersShaComposer($passphrase);
$shaComposer->addParameterFilter(new ShaInParameterFilter); //optional
$directLinkRequest = new DirectLinkMaintenanceRequest($shaComposer);
$directLinkRequest->setPspid('123456');
$directLinkRequest->setUserId('postfinance-api-user');
$directLinkRequest->setPassword('postfinance-api-password');
$directLinkRequest->setPayId('order_1234');
$directLinkRequest->setOperation(DirectLinkMaintenanceRequest::OPERATION_AUTHORISATION_RENEW);
$directLinkRequest->validate();
// now create a url to be posted to PostFinance
// you have access to $directLinkRequest->toArray(), $directLinkRequest->getPostFinanceUri() and directLinkRequest->getShaSign()
EcommercePaymentResponse
<?php
use PostFinance\Ecommerce\EcommercePaymentResponse;
use PostFinance\ShaComposer\AllParametersShaComposer;
// ...
$ecommercePaymentResponse = new EcommercePaymentResponse($_REQUEST);
$passphrase = new Passphrase('my-sha-out-passphrase-defined-in-postfinance-interface');
$shaComposer = new AllParametersShaComposer($passphrase);
$shaComposer->addParameterFilter(new ShaOutParameterFilter); //optional
if($ecommercePaymentResponse->isValid($shaComposer) && $ecommercePaymentResponse->isSuccessful()) {
// handle payment confirmation
}
else {
// perform logic when the validation fails
}
CreateAliasResponse
<?php
use PostFinance\DirectLink\CreateAliasResponse;
use PostFinance\ShaComposer\AllParametersShaComposer;
// ...
$createAliasResponse = new CreateAliasResponse($_REQUEST);
$passphrase = new Passphrase('my-sha-out-passphrase-defined-in-postfinance-interface');
$shaComposer = new AllParametersShaComposer($passphrase);
$shaComposer->addParameterFilter(new ShaOutParameterFilter); //optional
if($createAliasResponse->isValid($shaComposer) && $createAliasResponse->isSuccessful()) {
// Alias creation is succesful, get the Alias object
$alias = $createAliasResponse->getAlias();
}
else {
// validation failed, retry?
}
DirectLinkPaymentResponse
As the DirectLink payment gets an instant feedback from the server (and no async response) we don't use the SHA validation., (*15)
<?php
use PostFinance\DirectLink\DirectLinkPaymentResponse;
$directLinkResponse = new DirectLinkPaymentResponse('postfinance-direct-link-result-as-xml');
if($directLinkResponse->isSuccessful()) {
// handle payment confirmation
} else {
// perform logic when the validation fails
}
Parameter filters
ParameterFilters are used to filter the provided parameters (no shit Sherlock).
Both ShaIn- and ShaOutParameterFilters are provided and are based on the parameter lists defined in the PostFinance documentation.
Parameter filtering is optional, but we recommend using them to enforce expected parameters., (*16)
Wallogit.com
marlon