- Why use this package?
- Getting started
- Caching
- Converting to and from arrays
- Creating a payment
- Retrieving a payment's details
- Authorizing a payment
- Refunds
- Payouts
- Merchant accounts
- Account identifiers
- Receiving webhook notifications
- Custom idempotency keys
- Custom API calls
- Error Handling
This package simplifies working with the TrueLayer API, by:
- Handling authentication (including token expiry) and caching
- Signing requests
- Managing idempotency keys, including retrying on conflicts
- Retrying failed requests, where it makes sense to do so
- Providing type-hinted methods and classes to work with
The library will require an HTTP client that implements PSR-18.
composer require truelayer/client
If a PSR-18 client isn't installed, Composer will let you know. You can simply require one, such as Guzzle:
composer require guzzlehttp/guzzle truelayer/client
You will need to go to the TrueLayer console and create your credentials which you can then provide to the Client configurator:
$client = \TrueLayer\Client::configure()
->clientId($clientId)
->clientSecret($clientSecret)
->keyId($kid)
->pemFile($pemFilePath) // Or ->pem($contents) Or ->pemBase64($contents)
->create();
By default, the client library will initialise in sandbox
mode. To switch to production call useProduction()
:
$client = \TrueLayer\Client::configure()
...
->useProduction() // optionally, pass a boolean flag to toggle between production/sandbox mode.
->create();
This library assumes that your client_id is issued with the payments
scope. Depending on your account type this may
not be the case and the authentication server will return an invalid_scope
error. You can override the scopes used by
the library with the scopes()
method:
$client = \TrueLayer\Client::configure()
...
->scopes('foo', 'bar')
->create();
If needed, you can also provide your own HTTP client instance:
$client = \TrueLayer\Client::configure()
...
->httpClient($myPSR18Client)
->create();
The client library supports caching the client_credentials
grant access token needed to access, create and modify
resources on TrueLayer's systems. In order to enable it, you need to provide an implementation of
the PSR-16 common caching interface and a 32-bytes encryption key.
You can generate a random encryption key by running openssl rand -hex 32
. This key must be considered secret and
stored next to the client secrets obtained from TrueLayer's console.
$client = \TrueLayer\Client::configure()
...
->cache($cacheImplementation, $encryptionKey)
->create();
A good example of a caching library that implements PSR-16 is illuminate/cache.
If you want to skip calling each setter method, you can use arrays to create any resource:
$client->beneficiary()->fill($beneficiaryData);
$client->user()->fill($userData);
$client->payment()->fill($paymentData);
// etc...
You can also convert any resource to array. This can be convenient if you need to output it to json for example:
$paymentData = $client->getPayment($paymentId)->toArray();
Merchant account beneficiary
// 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);
If your merchant account is configured for payment verification then you have the option to enable automated remitter verification for your Merchant Account payment:
$remitterVerification = $client
->remitterVerification()
->automated()
->remitterName(true)
->remitterDateOfBirth(true);
$beneficiary = $client->beneficiary()
->merchantAccount()
->merchantAccountId('a2dcee6d-7a00-414d-a1e6-8a2b23169e00')
->verification($remitterVerification);
External account beneficiary - Sort code & account number
$beneficiary = $client->beneficiary()->externalAccount()
->reference('Transaction reference')
->accountHolderName('John Doe')
->accountIdentifier(
$client->accountIdentifier()->sortCodeAccountNumber()
->sortCode('010203')
->accountNumber('12345678')
);
External account beneficiary - IBAN
$beneficiary = $client->beneficiary()->externalAccount()
->reference('Transaction reference')
->accountHolderName('John Doe')
->accountIdentifier(
$client->accountIdentifier()->iban()
->iban('GB53CLRB04066200002723')
);
use TrueLayer\Constants\UserPoliticalExposures;
$user = $client->user()
->name('Jane Doe')
->phone('+44123456789')
->email('jane.doe@truelayer.com')
->dateOfBirth('2024-01-01');
// You can also set the user's political exposure field if you need to
$user->politicalExposure(UserPoliticalExposures::CURRENT);
You are also able to set the user's address:
$address = $client->user()
->address()
->addressLine1('The Gilbert')
->addressLine2('City of')
->city('London')
->state('London')
->zip('EC2A 1PX')
->countryCode('GB');
You can create a bank transfer payment method with minimal configuration:
$paymentMethod = $client->paymentMethod()->bankTransfer()
->beneficiary($beneficiary);
Optionally, you can filter the providers that will be returned in the authorisation flow:
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);
Alternatively, you can preselect the provider that is going to be used in the authorisation flow as well as the payment scheme that the payment is going to be sent on:
// 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);
You can also enable payment retries, but make sure you can handle the attempt_failed
payment status beforehand:
$paymentMethod = $client->paymentMethod()->bankTransfer()
->enablePaymentRetry()
->beneficiary($beneficiary);
$payment = $client->payment()
->user($user)
->amountInMinor(1)
->currency(\TrueLayer\Constants\Currencies::GBP) // You can use other currencies defined in this class.
->paymentMethod($paymentMethod)
->create();
You then get access to the following methods:
$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
If you prefer, you can work directly with arrays by calling the fill
method:
$paymentData = [
'amount_in_minor' => 1,
'currency' => Currencies::GBP,
'payment_method' => [
'type' => PaymentMethods::BANK_TRANSFER,
'beneficiary' => [
'account_identifier' => [
'account_number' => '12345678',
'sort_code' => '010203',
'type' => 'sort_code_account_number',
],
'reference' => 'Transaction reference',
'account_holder_name' => 'John Doe',
'type' => 'external_account',
],
'provider_selection' => [
'type' => PaymentMethods::PROVIDER_TYPE_USER_SELECTION,
'filter' => [
'countries' => [
Countries::GB,
],
'release_channel' => ReleaseChannels::PRIVATE_BETA,
'customer_segments' => [
CustomerSegments::RETAIL,
],
'provider_ids' => [
'mock-payments-gb-redirect',
],
'excludes' => [
'provider_ids' => [],
],
],
],
],
];
$payment = $client->payment()->fill($paymentData)->create();
TrueLayer's Hosted Payment Page provides a high-converting UI for payment authorization that supports, out of the box, all action types. You can easily get the URL to redirect to after creating your payment:
$url = $client->payment()
...
->create()
->hostedPaymentsPage()
->returnUri('http://www.mymerchantwebsite.com')
->primaryColour('#000000')
->secondaryColour('#e53935')
->tertiaryColour('#32329f')
->toUrl();
$payment = $client->getPayment($paymentId);
$payment->getId();
$payment->getUserId();
$payment->getAmountInMinor();
$payment->getCreatedAt();
$payment->getCurrency();
$payment->getPaymentMethod();
$payment->toArray();
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();
}
}
You can check for the status by using one of the following helper methods:
$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.
Or you can get the status as a string and compare it to the provided constants in PaymentStatus
:
$payment = $client->getPayment($paymentId);
$payment->getStatus() === \TrueLayer\Constants\PaymentStatus::AUTHORIZATION_REQUIRED;
Payment with this status is on its initial phase where no action beyond the creation of the payment was taken.
use TrueLayer\Interfaces\Payment\PaymentAuthorizationRequiredInterface;
if ($payment instanceof PaymentAuthorizationRequiredInterface) {
// Your logic here, you would normally start the authorization process.
}
Payment has its authorization_flow started, but the authorization has not completed yet
A payment in Authorizing
will expose 2 additional methods for retrieving:
- the authorization flow config
- the next action in the payment authorization user journey
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();
}
This action indicates that the user needs to select a provider from the provided list. To render the provider list, each provider comes with helpful methods for retrieving the name, logo, id, etc.
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();
}
}
This action indicates that the user needs to be redirected to complete the authorization process.
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
}
Payment has successfully completed its authorization flow
use TrueLayer\Interfaces\Payment\PaymentAuthorizedInterface;
if ($payment instanceof PaymentAuthorizedInterface) {
$payment->getAuthorizationFlowConfig(); // see authorization flow config
}
Payment has been accepted by the bank
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
}
Payment can transition into this state if the beneficiary account was a merchant account within Truelayer, and Truelayer has observed the money to be settled.
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
}
Payment has failed. The reason for failure can be observed in failure_reason field on the payment resource
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_required`, `authorizing` or `authorized`
$payment->getFailureReason(); // The reason the payment failed. Handle unexpected values gracefully as an unknown failure.
$payment->getAuthorizationFlowConfig(); // see authorization flow config
}
Status only available when you enable payment retries.
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_required`, `authorizing` or `authorized`
$payment->getFailureReason(); // The reason the payment failed. Handle unexpected values gracefully as an unknown failure.
$payment->getAuthorizationFlowConfig(); // see authorization flow config
}
This object provides information about the authorization flow the payment went through.
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.
}
}
You are encouraged to use our HPP which collects all payment information required from your users and guides them through the payment authorisation journey. To do this simply redirect to the HPP after creating a payment. See Redirecting to HPP to get started.
In some cases you may want to start the authorization flow manually (for example if you want to render your own provider selection screen).
This library has incomplete support for the authorization flow. To complete the authorization flow, you will need to eventually redirect the user to the HPP or implement missing features using direct API calls ( see Custom API calls).
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();
Once the authorization flow has been started, refer to Authorizing payments to understand how to handle the returned actions.
If your payment requires selecting a provider as its next action, you can render the provider list and then submit the
user selection using the submitProvider
method:
$client->submitPaymentProvider($payment, $provider);
Refunds are only supported for settled merchant account payments.
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[]
Alternatively, if you already have a payment instance you can use the following convenience methods:
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();
}
$accountIdentifier = $client->accountIdentifier()
->iban()
->iban('GB29NWBK60161331926819');
$beneficiary = $client->payoutBeneficiary()->externalAccount()
->accountHolderName('John Doe')
->reference('My reference')
->accountIdentifier($accountIdentifier);
$payout = $client->payout()
->amountInMinor(1)
->beneficiary($beneficiary)
->currency(\TrueLayer\Constants\Currencies::GBP)
->merchantAccountId($merchantAccount->getId())
->create();
$payout->getId();
$beneficiary = $client->payoutBeneficiary()->paymentSource()
->paymentSourceId($paymentSourceId)
->reference('My reference')
->userId($user->getId());
$payout = $client->payout()
->amountInMinor(1)
->beneficiary($beneficiary)
->currency(\TrueLayer\Constants\Currencies::GBP)
->merchantAccountId($merchantAccount->getId())
->create();
$payout->getId();
$beneficiary = $client->payoutBeneficiary()
->businessAccount()
->reference('My reference');
$payout = $client->payout()
->amountInMinor(1)
->beneficiary($beneficiary)
->currency(\TrueLayer\Constants\Currencies::GBP)
->merchantAccountId($merchantAccount->getId())
->create();
$payout->getId();
use TrueLayer\Interfaces\Payout\PayoutRetrievedInterface;
use TrueLayer\Interfaces\Payout\PayoutPendingInterface;
use TrueLayer\Interfaces\Payout\PayoutAuthorizedInterface;
use TrueLayer\Interfaces\Payout\PayoutExecutedInterface;
use TrueLayer\Interfaces\Payout\PayoutFailedInterface;
use TrueLayer\Constants\PayoutStatus;
$payout = $client->getPayout($payoutId);
// All payout statuses implement this common interface
if ($payout instanceof PayoutRetrievedInterface) {
$payout->getId();
$payout->getCurrency();
$payout->getAmountInMinor();
$payout->getMerchantAccountId();
$payout->getStatus();
$payout->getBeneficiary();
$payout->getCreatedAt();
}
// Pending payouts
if ($payout instanceof PayoutPendingInterface) {
$payout->getStatus(); //PayoutStatus::PENDING
}
// Authorized payouts
if ($payout instanceof PayoutAuthorizedInterface) {
$payout->getStatus(); //PayoutStatus::AUTHORIZED
}
// Executed payouts
if ($payout instanceof PayoutExecutedInterface) {
$payout->getStatus(); //PayoutStatus::EXECUTED
$payout->getExecutedAt();
}
// Failed payouts
if ($payout instanceof PayoutFailedInterface) {
$payout->getStatus() // PayoutStatus::FAILED
$payout->getFailedAt();
$payout->getFailureReason();
}
Listing all merchant accounts:
$merchantAccounts = $client->getMerchantAccounts(); // MerchantAccountInterface[]
Retrieving an account by id:
$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.
}
You can register to receive notifications about your payment or mandate statuses via webhooks. The URI endpoint for the webhook can be configured in the Console
⚠️ All incoming webhook requests must have their signatures verified, otherwise you run the risk of accepting fraudulent payment status events.
This library makes handling webhook events easy and secure. You do not need to manually verify the incoming request
signature as it is done for you. You should add the code below to your webhook endpoint; Alternatively the webhook
service can be configured in your IoC container and in your endpoint you can simply call $webhook->execute()
.
If you already have access to a client instance, it's as easy as:
$webhook = $client->webhook();
Alternatively, you can also create an instance from scratch:
$webhook = \TrueLayer\Webhook::configure()
->httpClient($httpClient)
->cache($cacheImplementation, $encryptionKey) // optional, but recommeded. See Caching
->useProduction($useProduction) // bool
->create();
You handle events by registering handlers (closures or invokable classes) for the event types you care about. You can have as many handlers as you wish, however please note the order of execution is not guaranteed.
Your handlers will only execute after the request signature is verified, and the incoming webhook type is matched to the interface you typehinted in your handler.
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();
This library supports handlers for the following event types:
- payment_executed
- payment_settled
- payment_failed
- refund_executed
- refund_failed
- payout_executed
- payout_failed
You can also handle other event types by typehinting TrueLayer\Interfaces\Webhook\EventInterface
in your handler. You can then get the payload data by calling the getBody()
method on your variable.
All events inherit from EventInterface
.
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();
By default the webhook service will use php globals to read the endpoint path and request headers and body. This
behaviour can be overriden if necessary (for example you may be calling execute()
in a queued job.):
$client->webhook()
->handlers(...)
->path('/my/custom/path')
->headers($headers) // flat key-value array
->body($body) // the raw request body string
->execute();
If the webhook signature cannot be verified, a \TrueLayer\Exceptions\WebhookVerificationFailedException will be thrown. A number of other exceptions will be thrown when the webhook service is misconfigured, please see error handling
All account identifiers implement a common interface, so you can access:
$accountIdentifier->getType();
$accountIdentifier->toArray();
Based on the specific type, you can get more information:
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();
}
By default, the client will generate and manage idempotency keys for you. However, there are cases when you might want
to set your own idempotency keys and you can do this by using the requestOptions
setter when creating a resource.
// 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();
You can use the client library to make your own API calls without worrying about authentication or request signing:
$responseData = $client->getApiClient()->request()->uri('/merchant-accounts')->get();
$responseData = $client->getApiClient()->request()
->uri('/payments')
->payload($myData)
->header('My Header', 'value')
->post();
The client library throws the following exceptions:
Thrown according to the PSR-18 specification, if the HTTP client is unable to send the request at all or if the response could not be parsed into a PSR-7 response object.
Psr\Http\Client\ClientExceptionInterface
All custom exceptions will extend from the base TrueLayer\Exceptions\Exception
class.
Thrown if the API response is not a 2xx status.
\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
Thrown if the request data cannot be json encoded prior to calling the APIs.
\TrueLayer\Exceptions\ApiRequestJsonSerializationException
Thrown when a provided argument is invalid, for example an invalid beneficiary type
\TrueLayer\Exceptions\InvalidArgumentException
Thrown if the request signer cannot be initialised or signing fails.
\TrueLayer\Exceptions\SignerException
Thrown when the client library fails to encrypt a payload that needs to be cached.
\TrueLayer\Exceptions\EncryptException
Thrown if the client library fails to decrypt the value of a cached key.
\TrueLayer\Exceptions\DecryptException
Thrown when the webhook service cannot retrieve TL's public keys.
\TrueLayer\Exceptions\TLPublicKeysNotFound
Thrown when the webhook service is provided with an invalid handler.
\TrueLayer\Exceptions\WebhookHandlerException
Thrown when the webhook service cannot get the request body, signature header or the provided handlers have invalid arguments.
\TrueLayer\Exceptions\WebhookHandlerInvalidArgumentException
Thrown when the webhook signature cannot be verified.
\TrueLayer\Exceptions\WebhookVerificationFailedException