- Documentation
If you're accessing your own account data (either as an individual or corporate), see Internal use. If you're accessing Investec customer data, see External use.
See the the API documentation for response contents.
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);
The Sandbox API also has public credentials for testing with. Consult the API documentation for details.
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.
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();
//Now you can make requests to the appropriate API section, .e.g Private Banking
$api = $connector->privateBanking($authenticator);
To customise the access token's API scope, you can do so in the getAccessToken
call:
//...
$authenticator = $connector->getAccessToken(['accounts', 'transactions']);
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);
//Now you can make requests to the appropriate API section, .e.g Private Banking
$api = $connector->privateBanking($authenticator);
To customise the access token's API scope, you can do so in the getAuthorizationUrl
call:
//...
$authUrl = $connector->getAuthorizationUrl($redirectUri, ['accounts', 'transactions']);
//...
In the Personal & External use examples above, you're able to specify which scopes you'll be using for this access token.
For Internal use, you'll need to enable the relevant scope permission when you generate your API key. See Internal use for more information.
The scopes available are:
accounts
balances
beneficiarypayments
cards
statements
taxcertificates
transactions
transfers
By default only the accounts
scope is used. To change the scopes used, you can do this:
$scopes = [...]; //your scopes here
$connector->oauthConfig()->setDefaultScopes($scopes);
$api->getAccounts();
Will return an array of accounts. Each of these will contain an accountNumber
and an accountId
. The former is the bankingaccount number, and the latter is the internal ID of the account (this is the one to use in the API).
$api->getAccountBalance($accountIdentifier);
$accountIdentifier
is the internal identifier from thegetAccounts
request.
Returns an object containing the account ID, current balance, available balance, and currency.
$api->getAccountTransactions($accountIdentifier, $fromDate, $toDate);
$accountIdentifier
is the internal identifier from thegetAccounts
request.$fromDate
and$toDate
are optional filtering parameters that filter against the transactions'postingDate
. The expected date format isYYYY-MM-DD
, e.g.2021-05-01
.$transactionType
is an optional filtering parameter. It maps onto Investec's base transaction types. Use theInvestecSdkPhp\Enumerations\TransactionType
enumeration here.
Returns an array of transactions.
Uses the V2 version of this endpoint. Support for the deprecated endpoint is not planned.
The endpoint accepts a list of objects to handle multiple transfers.
use \InvestecSdkPhp\DataTransferObjects\PrivateBanking\TransferMultiple\TransferMultipleDto;
$transferMultipleDto = new TransferMultiple\TransferMultipleDto([
'accountInstances' => [
[
'beneficiaryAccountId' => 'XXXX',
'amount' => 100, //Remember - this is NOT in cents!
'myReference' => 'API Transfer',
'theirReference' => 'API Transfer',
]
// ...
]
]);
$api->transferMultiple($accountIdentifier, $transferMultipleDto);
$accountIdentifier
is the internal identifier from thegetAccounts
request.
Transfers money between accounts.
The endpoint accepts a list of objects to handle multiple transfers.
use \InvestecSdkPhp\DataTransferObjects\PrivateBanking\PayMultiple\PayMultipleDto;
$payMultipleDto = new PayMultiple\PayMultipleDto([
'accountInstances' => [
[
'beneficiaryId' => 'XXXX',
'amount' => 100, //Remember - this is NOT in cents!
'myReference' => 'API Transfer',
'theirReference' => 'API Transfer',
]
// ...
]
]);
$api->payMultiple($accountIdentifier, $payMultipleDto);
$accountIdentifier
is the internal identifier from thegetAccounts
request.
Used to pay beneficiaries.
$api->getBeneficiaries();
Returns an array of beneficiaries that have been linked to the user's profile.
$api->getBeneficiaryCategories();
Returns an array of the beneficiary categories used on the profile. It will also show which one is the default one.
$api->getProfiles();
Lists all profiles.
$api->getProfileAccounts($profileId);
Lists accounts for the given profile.
$api->getAuthorisationSetupDetails($profileId, $accountId);
List the authorisation setup details for the specified profile and accounts.
$api->getProfileBeneficiaries($profileId, $accountId);
Lists beneficiaries available to the given profile & account.
Note: This and Get Document both require your API token to have the taxcertificates
or statements
scopes.
$api->getDocuments($accountId, $fromDate, $toDate);
Lists available documents in the given date range. Otherwise defaults to documents available in the last month until today.
$api->getDocument($accountId, $documentType, $documentDate);
Retrieves the specified document type using the account ID, docuemnt type and date.
Note: According to the documentation, this API is only available via the 3-legged OAuth API (i.e. business use for clients), so it is only made available through the InvesteOAuthConnector
class.
Note: It's unclear if this API is only available for internal or external use. For now, it is added to both connectors.
Not yet implemented.
Not yet implemented.
Not yet implemented.
Note: The only current valid value for action
is Approve
.
Investec accounts (at least consumer ones by default) have a credit/overdraft facility, which is why you'll see currentBalance
and availableBalance
have large differences.
postingDate
is the date the transaction affects your balance, and is the one used for filtering.transactionDate
is the date the transaction physically occurred, e.g. when the card was swiped.
Currently I don't know the difference with value date and action date compared to the above two.
Investec has its own transaction types that all transactions automatically fall into:
- Card Purchases
- ATM Withdrawals
- Online Banking Payments
- Deposits
- Debit Orders
- Budget Instalments
- Faster Pay
- Fees And Interest
This package provides a TransactionType
enum for convenience.
These categories are user-created in their Investec app/online banking. By default the only category is Not Categorised
.