README

Investec API SDK for PHP

This is a PHP SDK for Investec's API, using Saloon.

This is a community-made package, and not directly affiliated with Investec.

Support

Installation

You can install the package via composer:

composer require nikspyratos/investec-sdk-php

NOTE: Currently, the stable release only includes support for authorization (both personal and 3-legged OAuth) and the Private Banking API. Other APIs are written but untested. See Roadmap for more details.

If you would like to use these other APIs, install from the main branch:

composer require nikspyratos/investec-sdk-php:"dev-main"

Usage

See the package documentation and API documentation for more details.

If you're accessing your own account data, see Internal use. If you're accessing Investec customer data, see External use.

See Environments for accessing the Sandbox environment.

Internal use

Firstly, make sure you've obtained your API credentials - this is how you get your client ID, secret and API key.

Note: Internal use access tokens have a lifespan of 30 minutes.

use InvestecSdkPhp\Connectors\InvestecConnector;

$clientId = '';
$clientSecret = '';
$apiKey = '';

//Initialise the API Connector
$connector = new InvestecConnector($clientId, $clientSecret, $apiKey);

//Get an access token
$authenticator = $connector->getAccessToken();

//Use it to authenticate requests for Private Banking
$api = $connector->privateBanking($authenticator);

//Have fun!
$data = $api->getAccounts();

External use

See API documentation for details.

Your organisation will need to chat with Investec directly to get access. The Investec API uses an OAuth flow for the customer to grant access to you for their data.

Reminder: This package is not affiliated with Investec.

use InvestecSdkPhp\Connectors\InvestecOAuthConnector;

$clientId = '';
$clientSecret = '';
$redirectUri = '';

//Initialise the API Connector
$connector = new InvestecOAuthConnector($clientId, $clientSecret);

//Create an OAuth authorization URL. You redirect your user to this
$authUrl = $connector->getAuthorizationUrl($redirectUri);

After being redirected back to your specified $redirectUri, you should have a code. Proceed as usual:

//Authorization code from the redirect
$code = ''

//Initialise the API Connector
$connector = new InvestecOAuthConnector($clientId, $clientSecret);

//Get an access token - this will still require the redirect URI
$authenticator = $connector->getAccessToken($redirectUri, $code);

//Use it to authenticate requests for Private Banking
$api = $connector->privateBanking($authenticator);

//Have fun!
$data = $api->getAccounts();

Environments

The API offers two environments: Sandbox and Production.

By default this SDK will use the Production environment. To change this, you may specify the environment using the provided enum like so:

use InvestecSdkPhp\Enumerations\Environment;
$connector = new InvestecConnector($clientId, $clientSecret, Environment::SANDBOX);

Data Transfer Objects

For Transfer Multiple and Pay Multiple endpoints, arrays of beneficiaries/accounts are accepted.

To handle this in a structured manner this package uses dragon-code/simple-dto to build the DTOs with the required data.

Testing

Tests are set to run with sandbox credentials (which Investec provides us with, luckily).

cp .env.example .env

Then, copy the sandbox environment variable values from here into your .env file.

Then, to run tests:

vendor/bin/pest

TODO

Using the excellent Saloon SDK Generator, the remaining APIs have been implemented, save for some Forex API endpoints:

Update BOP Report - the input is massive and has several nested arrays and objects, resulting in a DTO nightmare currently.
Validate BOP Report - similar issues to Update BOP Report.
Upload file contents for document handle - documentation is unclear on how to fill in this data.

For the implemented endpoints, tests are either not working (sandbox credentials issue) or are unwritten. Given that, I'm not comfortable releasing a new stable version for these APIs. If you'd like to use these, change your package requirement to dev-main. At this time, there also hasn't been much demand for these APIs in this SDK, so it's preferrable to not do more work for code that won't be used. If you would like to see any of those APIs reach a stable release, please contribute by:

Letting us know if it works, any issues you run into, etc.
Make a PR with working tests for an API matching the existing testing style, using PestPHP
Make a PR updating the Documentation with usage guides for the remaining endpoints

TODOs:

Re-evaluate how token handling and scopes are done in this package - Especially with Saloon's updates since launch (1), some of it may now be redundant.
Upgrade to Saloon v3
Re-evaluate existing implemented endpoints - may be changes due to API request/response additions/changes
Implement remaining endpoints described above
Get existing tests working again either with sandbox credentials or with mocking
Tests for remaining API endpoint groups

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Nik Spyratos
All Contributors
Saloon
Saloon SDK Generator for speeding up the work on the remaining APIs!

License

The MIT License (MIT). Please see License File for more information.

nikspyratos / investec-sdk-php

Maintainers

Details