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.

Requirements:

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!

Installation:

The library is PSR-4 compliant and the simplest way to install it is via composer:

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.

The library also allows:

Fetching order information via PostFinance API using DirectLinkQueryRequest
Executing maintenance request via PostFinance API using DirectLinkMaintenanceRequest

SHA Composers

PostFinance provides 2 methods to generate a SHA sign:

"Main parameters only"

Implementation using this library is trivial:

  <?php
    use PostFinance\ShaComposer\LegacyShaComposer;
    $shaComposer = new LegacyShaComposer($passphrase);

"Each parameter followed by the passphrase"

Implementation using this library is trivial:

    <?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.

EcommercePaymentRequest and FormGenerator

    <?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.

    <?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.

wysow / wysow-postfinance

readme

PostFinance PHP library

Installation:

Overview

SHA Composers

EcommercePaymentRequest and FormGenerator

CreateAliasRequest

DirectLinkPaymentRequest

DirectLinkQueryRequest

DirectLinkQueryRequest

DirectLinkMaintenanceRequest

EcommercePaymentResponse

CreateAliasResponse

DirectLinkPaymentResponse

Parameter filters