1. Go to this page and download the library: Download truelayer/client library. Choose the download type require.
2. Extract the ZIP file and open the index.php.
3. Add this code to the index.php.
<?php
require_once('vendor/autoload.php');
/* Start to develop here. Best regards https://php-download.com/ */
truelayer / client example snippets
$client = \TrueLayer\Client::configure()
->clientId($clientId)
->clientSecret($clientSecret)
->keyId($kid)
->pemFile($pemFilePath) // Or ->pem($contents) Or ->pemBase64($contents)
->create();
$client = \TrueLayer\Client::configure()
...
->useProduction() // optionally, pass a boolean flag to toggle between production/sandbox mode.
->create();
// If the merchant account id is known:
$beneficiary = $client->beneficiary()->merchantAccount()
->merchantAccountId('a2dcee6d-7a00-414d-a1e6-8a2b23169e00');
// Alternatively you can retrieve merchant accounts and use one of them directly:
$merchantAccounts = $client->getMerchantAccounts();
// Select the merchant account you need...
$merchantAccount = $merchantAccounts[0];
$beneficiary = $client->beneficiary()->merchantAccount($merchantAccount);
use TrueLayer\Constants\UserPoliticalExposures;
$user = $client->user()
->name('Jane Doe')
->phone('+44123456789')
->email('[email protected]')
->dateOfBirth('2024-01-01');
// You can also set the user's political exposure field if you need to
$user->politicalExposure(UserPoliticalExposures::CURRENT);
use TrueLayer\Constants\Countries;
use TrueLayer\Constants\CustomerSegments;
use TrueLayer\Constants\ReleaseChannels;
// You can filter the providers that will be returned:
$filter = $client->providerFilter()
->countries([Countries::GB, Countries::ES])
->customerSegments([CustomerSegments::RETAIL, CustomerSegments::CORPORATE])
->releaseChannel(ReleaseChannels::PRIVATE_BETA)
->excludesProviderIds(['provider-id'])
// You can also filter providers by the schemes they support:
$schemeSelection = $client->schemeSelection()->userSelected(); // Let the user select. You must provide your own UI for this.
$schemeSelection = $client->schemeSelection()->instantOnly(); // Only allow providers that support instant payments
$schemeSelection = $client->schemeSelection()->instantPreferred(); // Prefer providers that allow instant payments, but allow defaulting back to non-instant payments if unavailable.
// For instant only and instant preferred, you can also allow or disallow remitter fees:
$schemeSelection->allowRemitterFee(true); // Unless explicitly set, this will default to false.
// Create the provider selection configuration
$providerSelection = $client->providerSelection()->userSelected()
->filter($filter)
->schemeSelection($schemeSelection);
// Create the payment method
$paymentMethod = $client->paymentMethod()->bankTransfer()
->providerSelection($providerSelection);
// Preselect the payment scheme
$schemeSelection = $client->schemeSelection()
->preselected()
->schemeId('faster_payments_service');
// Preselect the provider
$providerSelection = $client->providerSelection()
->preselected()
->providerId('mock-payments-gb-redirect')
->schemeSelection($schemeSelection);
// Create the payment method
$paymentMethod = $client->paymentMethod()->bankTransfer()
->providerSelection($providerSelection);
$payment = $client->payment()
->user($user)
->amountInMinor(1)
->currency(\TrueLayer\Constants\Currencies::GBP) // You can use other currencies defined in this class.
->paymentMethod($paymentMethod)
->create();
$payment->getId(); // The payment id
$payment->getResourceToken(); // The resource token
$payment->getDetails(); // Get the payment details, same as $client->getPayment($paymentId)
$payment->hostedPaymentsPage(); // Get the Hosted Payments Page helper, see below.
$payment->toArray(); // Convert to array
use TrueLayer\Interfaces\PaymentMethod\BankTransferPaymentMethodInterface;
use TrueLayer\Interfaces\Beneficiary\ExternalAccountBeneficiaryInterface;
use TrueLayer\Interfaces\Beneficiary\MerchantBeneficiaryInterface;
$method = $client->getPayment($paymentId)->getPaymentMethod();
if ($method instanceof BankTransferPaymentMethodInterface) {
$providerSelection = $method->getProviderSelection();
$beneficiary = $method->getBeneficiary();
$beneficiary->getAccountHolderName();
if ($beneficiary instanceof ExternalAccountBeneficiaryInterface) {
$beneficiary->getReference();
$beneficiary->getAccountIdentifier(); // See account identifiers documentation
}
if ($beneficiary instanceof MerchantBeneficiaryInterface) {
$beneficiary->getReference();
$beneficiary->getMerchantAccountId();
}
}
$payment = $client->getPayment($paymentId);
$payment->isAuthorizationRequired();
$payment->isAuthorizing();
$payment->isAuthorized(); // Will also return false when the payment has progressed to executed, failed or settled states.
$payment->isExecuted(); // Will also return false when the payment has progressed to failed or settled states.
$payment->isSettled();
$payment->isFailed(); // Payment has failed
$payment->isAttemptFailed(); // Payment attempt has failed, only available if payment retries are enabled.
use TrueLayer\Interfaces\Payment\PaymentAuthorizationRequiredInterface;
if ($payment instanceof PaymentAuthorizationRequiredInterface) {
// Your logic here, you would normally start the authorization process.
}
use TrueLayer\Interfaces\Payment\PaymentAuthorizingInterface;
if ($payment instanceof PaymentAuthorizingInterface) {
$payment->getAuthorizationFlowConfig(); // see authorization flow config
// Will return a \TrueLayer\Interfaces\Payment\AuthorizationFlow\Action\ActionInterface
$payment->getAuthorizationFlowNextAction();
}
use TrueLayer\Interfaces\Payment\AuthorizationFlow\Action\ProviderSelectionActionInterface;
$nextAction = $payment->getAuthorizationFlowNextAction();
if ($nextAction instanceof ProviderSelectionActionInterface) {
foreach ($nextAction->getProviders() as $provider) {
$provider->getId();
$provider->getDisplayName();
$provider->getCountryCode();
$provider->getLogoUri();
$provider->getIconUri();
$provider->getBgColor();
}
}
use TrueLayer\Interfaces\Payment\AuthorizationFlow\Action\RedirectActionInterface;
$nextAction = $payment->getAuthorizationFlowNextAction();
if ($nextAction instanceof RedirectActionInterface) {
$nextAction->getUri(); // The URL the end user must be redirected to
$nextAction->getProvider(); // The provider object, see available methods above.
}
use TrueLayer\Interfaces\Payment\AuthorizationFlow\Action\WaitActionInterface;
$nextAction = $payment->getAuthorizationFlowNextAction();
if ($nextAction instanceof WaitActionInterface) {
// your logic here
}
use TrueLayer\Interfaces\Payment\PaymentAuthorizedInterface;
if ($payment instanceof PaymentAuthorizedInterface) {
$payment->getAuthorizationFlowConfig(); // see authorization flow config
}
use TrueLayer\Interfaces\Payment\PaymentExecutedInterface;
if ($payment instanceof PaymentExecutedInterface) {
$payment->getExecutedAt(); // The date and time the payment was executed at
$payment->getAuthorizationFlowConfig(); // See authorization flow config
}
use TrueLayer\Interfaces\Payment\PaymentSettledInterface;
if ($payment instanceof PaymentSettledInterface) {
$payment->getExecutedAt(); // The date and time the payment was executed at
$payment->getSettledAt(); // The date and time the payment was settled at
$payment->getAuthorizationFlowConfig(); // See authorization flow config
$payment->getSourceOfFunds(); // See source of funds
}
use TrueLayer\Interfaces\Payment\PaymentFailedInterface;
if ($payment instanceof PaymentFailedInterface) {
$payment->getFailedAt(); // The date and time the payment failed at
$payment->getFailureStage(); // The status the payment was when it failed, one of `authorization_
use TrueLayer\Interfaces\Payment\PaymentAttemptFailedInterface;
if ($payment instanceof PaymentAttemptFailedInterface) {
$payment->getFailedAt(); // The date and time the payment failed at
$payment->getFailureStage(); // The status the payment was when it failed, one of `authorization_
use TrueLayer\Interfaces\Payment\PaymentExecutedInterface;
if ($payment instanceof PaymentExecutedInterface) {
$config = $payment->getAuthorizationFlowConfig();
$config->isRedirectSupported() // Is redirect supported or not
$config->getRedirectReturnUri(); // The URL the user will be redirected back once the flow on the third-party's website is completed
$config->isProviderSelectionSupported(); // Is provider selection supported or not
}
use TrueLayer\Interfaces\Payment\PaymentExecutedInterface;
use TrueLayer\Interfaces\Payment\PaymentSettledInterface;
use TrueLayer\Interfaces\SchemeIdentifier\ScanDetailsInterface;
use TrueLayer\Interfaces\SchemeIdentifier\IbanDetailsInterface;
use TrueLayer\Interfaces\SchemeIdentifier\BbanDetailsInterface;
use TrueLayer\Interfaces\SchemeIdentifier\NrbDetailsInterface;
if ($payment instanceof PaymentExecutedInterface || $payment instanceof PaymentSettledInterface) {
$paymentSource = $payment->getPaymentSource();
$paymentSource->getAccountHolderName(); // The unique ID for the external account
$paymentSource->getId();
$paymentSource->toArray();
foreach ($paymentSource->getAccountIdentifiers() as $accountIdentifier) {
// See 'Account identifiers' for available methods.
}
}
use TrueLayer\Constants\FormInputTypes;
$payment = $client->payment()->create();
// If you are planning to start the authorization flow manually then hand over to the HPP:
$payment->authorizationFlow()
->returnUri($myReturnUri)
->useHPPCapabilities()
->start();
// If you are planning to build a fully custom UI, you need to manually specify which features your UI is able to support:
$payment->authorizationFlow()
->returnUri($myReturnUri)
->enableProviderSelection() // Can the UI render a provider selection screen?
->enableSchemeSelection() // Can the UI render a scheme selection screen?
->enableUserAccountSelection() // Can the UI render a user account selection screen?
->formInputTypes([FormInputTypes::TEXT, FormInputTypes::TEXT_WITH_IMAGE, FormInputTypes::SELECT]) // Can the UI render form inputs for the end user to interact with? Which input types can it handle?
->start();
use TrueLayer\Interfaces\Payment\RefundRetrievedInterface;
use TrueLayer\Interfaces\Payment\RefundExecutedInterface;
use TrueLayer\Interfaces\Payment\RefundFailedInterface;
// Create and get the refund id
$refundId = $client->refund()
->payment($paymentId) // Payment ID, PaymentRetrievedInterface or PaymentCreatedInterface
->amountInMinor(1)
->reference('My reference')
->create()
->getId();
// Get a refund's details
$refund = $client->getRefund($paymentId, $refundId);
// Common refund methods
$refund->getId();
$refund->getAmountInMinor();
$refund->getCurrency();
$refund->getReference();
$refund->getStatus();
$refund->getCreatedAt();
$refund->isPending();
$refund->isAuthorized();
$refund->isExecuted();
$refund->isFailed();
// Executed refunds
if ($refund instanceof RefundExecutedInterface) {
$refund->getExecutedAt();
}
// Failed refunds
if ($refund instanceof RefundFailedInterface) {
$refund->getFailureReason();
$refund->getFailedAt();
}
// Get all refunds for a payment
$refunds = $client->getRefunds($paymentId); // RefundRetrievedInterface[]
use TrueLayer\Interfaces\Payment\PaymentSettledInterface;
if ($payment instanceof PaymentSettledInterface) {
// Create a refund
$refundId = $payment->refund()
->amountInMinor(1)
->reference('My reference')
->create()
->getId();
// Get a refund's details
$payment->getRefund($refundId)
// Get all refunds
$payment->getRefunds();
}
$merchantAccount = $client->getMerchantAccount('a2dcee6d-7a00-414d-a1e6-8a2b23169e00');
$merchantAccount->getAccountHolderName();
$merchantAccount->getAvailableBalanceInMinor();
$merchantAccount->getCurrentBalanceInMinor();
$merchantAccount->getCurrency();
$merchantAccount->getId();
foreach ($merchantAccount->getAccountIdentifiers() as $accountIdentifier) {
// See 'Account identifiers' for available methods.
}
$webhook = $client->webhook();
$webhook = \TrueLayer\Webhook::configure()
->httpClient($httpClient)
->cache($cacheImplementation, $encryptionKey) // optional, but recommeded. See Caching
->useProduction($useProduction) // bool
->create();
use TrueLayer\Interfaces\Webhook;
$client->webhook()
->handler(function (Webhook\EventInterface $event) {
// Do something on any event
})
->handler(function (Webhook\PaymentEventInterface $event) {
// Do something on any payment event
})
->handler(function (Webhook\PaymentExecutedEventInterface $event) {
// Do something on payment executed event only
})
->execute();
use TrueLayer\Interfaces\Webhook;
class LogEvents
{
public function __invoke(Webhook\EventInterface $event)
{
// Log event
}
}
class UpdateOrderStatus
{
public function __invoke(Webhook\PaymentExecutedEventInterface $event)
{
// Update your order when the payment is executed
}
}
// You can use ->handler()...
$client->webhook()
->handler(LogEvents::class)
->handler(UpdateOrderStatus::class)
->execute();
// Or you can use ->handlers()...
$client->webhook()
->handlers(
LogEvents::class,
UpdateOrderStatus::class
)
->execute();
// If you need to, you can also provide instances:
$client->webhook()
->handlers(
new LogEvents(),
new UpdateOrderStatus()
)
->execute();
use TrueLayer\Interfaces\Webhook;
$client->webhook()
->handler(function (Webhook\EventInterface $event) {
// handle any incoming event
$event->getEventId();
$event->getEventVersion();
$event->getSignature();
$event->getTimestamp();
$event->getType();
$event->getBody();
})
->handler(function (Webhook\PaymentEventInterface $event) {
// handle any payment event
$event->getPaymentId();
$paymentMethod = $event->getPaymentMethod();
$paymentMethod->getType();
if ($paymentMethod instanceof Webhook\PaymentMethod\BankTransferPaymentMethodInterface) {
$paymentMethod->getProviderId();
$paymentMethod->getSchemeId();
}
if ($paymentMethod instanceof Webhook\PaymentMethod\MandatePaymentMethodInterface) {
$paymentMethod->getMandateId();
}
})
->handler(function (Webhook\PaymentExecutedEventInterface $event) {
// handle payment executed
// Inherits from PaymentEventInterface so provides same methods plus:
$event->getExecutedAt();
$event->getSettlementRiskCategory();
})
->handler(function (Webhook\PaymentSettledEventInterface $event) {
// handle payment settled
// Inherits from PaymentEventInterface so provides same methods plus:
$event->getSettledAt();
$event->getSettlementRiskCategory();
$paymentSource = $event->getPaymentSource();
$paymentSource->getId();
$paymentSource->getAccountHolderName();
$paymentSource->getAccountIdentifiers(); // See Account Identifiers
})
->handler(function (Webhook\PaymentFailedEventInterface $event) {
// handle payment failed
// Inherits from PaymentEventInterface so provides same methods plus:
$event->getFailedAt();
$event->getFailureReason();
$event->getFailureStage();
})
->handler(function (Webhook\RefundEventInterface $event) {
// handle any refund event
$event->getPaymentId();
$event->getRefundId();
})
->handler(function (Webhook\RefundExecutedEventInterface $event) {
// handle refund executed
// Inherits from RefundEventInterface so provides same methods plus:
$event->getExecutedAt();
})
->handler(function (Webhook\RefundFailedEventInterface $event) {
// handle refund failed
// Inherits from RefundEventInterface so provides same methods plus:
$event->getFailedAt();
$event->getFailureReason();
})
->handler(function (Webhook\PayoutEventInterface $event) {
// handle any payout event
$event->getPayoutId();
$beneficiary = $event->getBeneficiary();
$beneficiary->getType();
if ($beneficiary instanceof Webhook\Beneficiary\BusinessAccountBeneficiaryInterface) {
$beneficiary->getType();
}
if ($beneficiary instanceof Webhook\Beneficiary\PaymentSourceBeneficiaryInterface) {
$beneficiary->getPaymentSourceId();
$beneficiary->getUserId();
}
})
->handler(function (Webhook\PayoutExecutedEventInterface $event) {
// handle payout executed
// Inherits from PayoutEventInterface so provides same methods plus:
$event->getExecutedAt();
})
->handler(function (Webhook\PayoutFailedEventInterface $event) {
// handle payout failed
// Inherits from PayoutEventInterface so provides same methods plus:
$event->getFailedAt();
$event->getFailureReason();
})
->execute();
$client->webhook()
->handlers(...)
->path('/my/custom/path')
->headers($headers) // flat key-value array
->body($body) // the raw request body string
->execute();
use TrueLayer\Interfaces\AccountIdentifier\ScanDetailsInterface;
use TrueLayer\Interfaces\AccountIdentifier\IbanDetailsInterface;
use TrueLayer\Interfaces\AccountIdentifier\NrbDetailsInterface;
use TrueLayer\Interfaces\AccountIdentifier\BbanDetailsInterface;
if ($accountIdentifier instanceof ScanDetailsInterface) {
$accountIdentifier->getAccountNumber();
$accountIdentifier->getSortCode();
}
if ($accountIdentifier instanceof IbanDetailsInterface) {
$accountIdentifier->getIban();
}
if ($accountIdentifier instanceof NrbDetailsInterface) {
$accountIdentifier->getNrb();
}
if ($accountIdentifier instanceof BbanDetailsInterface) {
$accountIdentifier->getBban();
}
// Create a RequestOptionsInterface instance and set your custom idempotency key
$requestOptions = $client->requestOptions()->idempotencyKey('my-custom-idempotency-key');
// Creating a payment with a custom idempotency key
$client->payment()
->paymentMethod($method)
->amountInMinor(10)
->currency('GBP')
->user($user)
->requestOptions($requestOptions)
->create();
// Creating a refund with a custom idempotency key
$client->refund()
->payment($paymentId)
->amountInMinor(1)
->reference('My reference')
->requestOptions($requestOptions)
->create();
// Creating a payout with a custom idempotency key
$client->payout()
->amountInMinor(1)
->currency(Currencies::GBP)
->merchantAccountId($accountId)
->beneficiary($payoutBeneficiary)
->requestOptions($requestOptions)
->create();
\TrueLayer\Exceptions\ApiResponseUnsuccessfulException
$e->getErrors(); // Get the errors provided by the API, as an array
$e->getStatusCode(); // The response status code
$e->getType(); // The error type, as a link to the TrueLayer docs
$e->getDetail(); // A description of the error message
$e->getTraceId(); // The TrueLayer error trace id