Skip to content

Latest commit

 

History

History
302 lines (217 loc) · 10.4 KB

INSTALL.md

File metadata and controls

302 lines (217 loc) · 10.4 KB
Raw

Installation and introduction

System requirements

  • PHP 5.5+
  • Curl

Installation with Composer

Currently this project only supports installation with Composer and it's available via Packagist (walle89/swedbank-json). Read more about Composer. Installation done in any outer way than with Composer is not supported.

composer require walle89/swedbank-json

Next, use the example code below.

Example code

This example uses security token with one time code as authentication method for listing bank statements.

<?php 
require 'vendor/autoload.php';

// Settings
$bankApp   = 'swedbank';
$username  = 198903060000; // Personal identity number (personnummer).
$cachePath = __DIR__.'/AppData.json';

if(empty($_POST['challengeResponse']))
{
   echo '
   <form action="" method="post">
       <p>Type 8 digit one time code generated by your security token</p>
       <label>One time code</label>
       <input id="challengeResponse" name="challengeResponse" type="text" />
       <button>Sign in</button>
   </form>';
   exit;
}
if(!is_numeric($_POST['challengeResponse']))
   exit('Wrong code!');

$appData  = new SwedbankJson\AppData($bankApp, $cachePath);
$auth     = new SwedbankJson\Auth\SecurityToken($appData, $username, $_POST['challengeResponse']);
$bankConn = new SwedbankJson\SwedbankJson($auth);

$accountInfo = $bankConn->accountDetails();
$bankConn->terminate(); // Sign out

echo 'Bank statements
<pre>';
print_r($accountInfo);

Alternative authentication methods

Besides authentication with security token with one time code, SwedbankJson also support authentication methods like Mobile BankID and "no authentication". Each method have it's benefits and limitations.

Information about and instructions for implementation can be read in authentication.md.

What is cache used for? What is App data?

App data is needed in order use Swedbank's Mobile Apps API and it's by default fetched from a remote file. For more information, read the App Data documentation.

Bank statements

Simple example

List bank statements for the first account.

$accountInfo = $bankConn->accountDetails(); // Selecting default account

$bankConn->terminate(); // Sign out

echo '<strong>Bank statements</strong>';
print_r($accountInfo);

The output should look like account details response sample.

Selecting specific account

To choose a specific account to get bank statements from, you can modify the above code to the following:

$accounts             = $bankConn->accountList(); // Account list
$transactionAccountID = $accounts->transactionAccounts[1]->id; // Temporary per session ID.

$accountInfo = $bankConn->accountDetails($transactionAccountID); // Select account 2

$bankConn->terminate(); // Sign out

echo '<strong>Accounts</strong>';
print_r($accounts);

echo '<strong>Bank statements</strong>';
print_r($accountInfo);

Syncing bank statements

A common use case is to save and compare bank statements to for example detect new transactions. One important thing to know is the IDs form the API can not and should not be used for this purpose. This is because they are only unique for the session. In the next session the transaction will have a new temporary ID.

One approach to solve this is combine date, description, currency and amount parameters to an identifier for that transaction. You can possibly add the accounting balance amount as an identifier for better accuracy.

Profile selector

The Swedbank API have support for multiple company profiles linked to a user. Do not forget to change BANK_APP to either swedbank_foretag or sparbanken_foretag.

$profiles = $bankConn->profileList(); // Profiles
$prfileID = $accounts->transactionAccounts[1]->id; // Temporary per session ID.

$accounts             = $bankConn->accountList($prfileID); // Available accounts based on the selected profile
$transactionAccountID = $accounts->transactionAccounts[0]->id; // Temporary per session ID.

$accountInfo = $bankConn->accountDetails($transactionAccountID);

$bankConn->terminate(); // Sign out

echo '<strong>Profiles</strong>';
print_r($profiles);

echo '<strong>Accounts</strong>';
print_r($profiles);

echo '<strong>Bank statements</strong>';
print_r($accountInfo);

Transaction Details

With some transaction rows, there can be additional data that can be fetched. A indicator of a transaction row has more details, is it has a details attribute containing a link to /v4/engagement/transactions/details.

$accountInfo = $bankConn->accountDetails();
$transactionDetails = $bankConn->transactionDetails($accountInfo->transactions[78]->details->id);

$bankConn->terminate(); // Sign out

echo '<strong>Transaction Details</strong>';
print_r($transactionDetails);

Quick balance

One of few APIs that can be accessed without BankID or security token. All you need is to get a SubscriptionId (see "How do I get a SubscriptionId?") SubscriptionId is a unique ID per account that can be used to get the following information:

  • Current total balance of the account
  • If there are notifications for the user (eg. newly received e-invoice)

This ID is supposed to be created and used each time you request quick balance.

<?php 
require 'vendor/autoload.php';

// Settings
$bankApp        = 'swedbank';
$subscriptionId = 'ExampleXX2GCi3333YpupYBDZX75sOme8Ht9dtuFAKE=';
$cachePath      = __DIR__.'/AppData.json';

$appData  = new SwedbankJson\AppData($bankApp, $cachePath);
$auth     = new SwedbankJson\Auth\UnAuth($appData);
$bankConn = new SwedbankJson\SwedbankJson($auth);

echo '<pre>';
var_dump($bankConn->quickBalance($subscriptionId));

How do I get a SubscriptionId?

The easiest way is use the code below. Do not forget to save SubscriptionId, once lost it cannot be recovered.

<?php 
require 'vendor/autoload.php';

session_start();

// Settings
$bankApp   = 'swedbank';
$username  = 8903060000; // Personal identity number (personnummer).
$cachePath = __DIR__.'/AppData.json';

// Sign in
if (!isset($_SESSION['swedbankjson_auth']))
{
    $appData = new SwedbankJson\AppData($bankApp, $cachePath);
    $auth = new SwedbankJson\Auth\MobileBankID($appData, $username);
    $auth->initAuth();
    exit('Please open the BankID app and confirm the login. Then reload this page.');
}

// Verify sign in
$auth = unserialize($_SESSION['swedbankjson_auth']);
if (!$auth->verify())
    exit("You reloaded the page, but the authentication has not been approved in the BankID app. Please try again.");

// You are in
$bankConn = new SwedbankJson\SwedbankJson($auth);

if (empty($_POST['quickbalanceSubscriptionID']))
{
    $quickBalanceAccounts = $bankConn->quickBalanceAccounts();

    echo '<form action="" method="post"><p>Select account for SubscriptionId</p><select name="quickbalanceSubscriptionID">';

    foreach ($quickBalanceAccounts->accounts as $account)
        echo '<option value="'.$account->quickbalanceSubscription->id.'">'.$account->name.'</option>';

    echo '</select><button>Create subscription</button></form>';
    exit;
}

$subInfo = $bankConn->quickBalanceSubscription($_POST['quickbalanceSubscriptionID']);
echo "<p>Your SubscriptionId: {$subInfo->subscriptionId}</p>
<p>Test it right away:</p>var_dump(\$bankConn->quickBalance('{$subInfo->subscriptionId}'));";

$auth->terminate(); // Sign out

Transfer money

Currently there is only support for money transfers between accounts owned by the user, or other types of transfers that do not need to be signed.

Examples of how to move the 0.99 SEK between two accounts.

echo '<pre>':
$baseInfo = $bankConn->baseInfo();

// Find accounts
print_r($baseInfo);

// Sholud be replaced with a form
// NOTE: Change this before run
$fromAccountId      = $baseInfo->fromAccountGroup[0]->accounts[0]->id;      // Ex. Sealery account. The ID is temporary per session
$recipientAccountId = $baseInfo->recipientAccountGroup[1]->accounts[3]->id; // Ex. Vecation saving account. The ID is temporary per session

// Register a transfare request
$result = $bankConn->registerTransfer(0.99, $fromAccountId, $recipientAccountId, 'From test', 'To test');

// See if the transfer request has been registered
print_r($result);

// Execute transfare queue
print_r($bankConn->confirmTransfers());

// If you like, check so that queue is empty
print_r($bankConn->listRegisteredTransfers());

$auth->terminate(); // Sign out

There is support to register multiple transfers and variations of transfers.

// Trasnfare without message
$bankConn->registerTransfer(0.99, $fromAccountId, $recipientAccountId);

// Scheduled transfer that will take place only once
$bankConn->registerTransfer(1000.00, $fromAccountId, $recipientAccountId, 'Gift', 'Gift', '2017-03-06');

// Periodized transfer date must be entered that acts as the start date.
// Possible periods are determined by 'periodicity', which is found in the results of the baseInfo().
// Examples of periods: ["NONE", "WEEKLY", "EVERY_OTHER_WEEK", "MONTHLY", "EVERY_OTHER_MONTH", "QUARTERLY", "SEMI_ANNUALLY", "ANNUALLY"]
$bankConn->registerTransfer(1000.00, $fromAccountId, $recipientAccountId, 'Gift', 'Gift', '2018-03-06', 'ANNUALLY');

// Confirm all transfares
print_r($bankConn->confirmTransfers());

// See if scheduled and allocated transfers are registered successfully.
print_r($bankConn->listConfirmedTransfers());

Be careful not to register two similar transfers (the same amount, the sending and receiving accounts and date), this will result as an error message from the API.

To delete a transfer can do the following.

// Remove unconfirmed transfer from queue 
$transfares = $bankConn->listRegisteredTransfers();
$bankConn->deleteTransfer($transfares->transferGroups[0]->transfers[0]->id);

// Remove scheduled or accrual transfer
$confirmedTransfares = $bankConn->listConfirmedTransfers();
$bankConn->deleteTransfer($confirmedTransfares->transferGroups[0]->transfers[2]->id);