Download the PHP package truelayer/client without Composer

Quick Links

1. Why use this package?
2. Getting started
3. Caching
4. Converting to and from arrays
5. Creating a payment
   1. Creating a beneficiary
   2. Creating a user
   3. Creating a payment method
   4. Creating the payment
   5. Creating a payment from an array
   6. Redirecting to the Hosted Payments Page
6. Retrieving a payment's details
   1. Get the user
   2. Get the payment method and beneficiary
   3. Check a payment's status
   4. Working with status specific payment fields
      1. Authorization Required Status
      2. Authorizing Status
         1. Provider selection action
         2. Redirect action
         3. Wait action
      3. Authorized Status
      4. Executed Status
      5. Settled Status
      6. Failed Status
      7. Attempt Failed Status
      8. Authorization flow config
      9. Source of funds
7. Cancel a payment
8. Authorizing a payment
9. Refunds
10. Payouts
11. Merchant accounts
12. Account identifiers
13. Receiving webhook notifications
14. Custom idempotency keys
15. Custom API calls
16. Error Handling

Why use this package?

This package simplifies working with the TrueLayer API, by:

1. Handling authentication (including token expiry) and caching
2. Signing requests
3. Managing idempotency keys, including retrying on conflicts
4. Retrying failed requests, where it makes sense to do so
5. Providing type-hinted methods and classes to work with

Getting started

Installation

The library will require an HTTP client that implements PSR-18.

If a PSR-18 client isn't installed, Composer will let you know. You can simply require one, such as Guzzle:

Initialisation

You will need to go to the TrueLayer console and create your credentials which you can then provide to the Client configurator:

By default, the client library will initialise in sandbox mode. To switch to production call useProduction():

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:

If needed, you can also provide your own HTTP client instance:

Caching

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.

A good example of a caching library that implements PSR-16 is illuminate/cache.

Converting to and from arrays

If you want to skip calling each setter method, you can use arrays to create any resource:

You can also convert any resource to array. This can be convenient if you need to output it to json for example:

Creating a payment

1. Creating a beneficiary

Merchant account beneficiary

If your merchant account is configured for payment verification then you have the option to enable automated remitter verification for your Merchant Account payment:

External account beneficiary - Sort code & account number

External account beneficiary - IBAN

2. Creating a user

You are also able to set the user's address:

3. Creating a payment method

You can create a bank transfer payment method with minimal configuration:

Optionally, you can filter the providers that will be returned in the authorisation flow:

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:

You can also enable payment retries, but make sure you can handle the attempt_failed payment status beforehand:

4. Creating the payment

You then get access to the following methods:

5. Creating a payment from an array

If you prefer, you can work directly with arrays by calling the fill method:

6. Redirecting to the Hosted Payments Page

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:

Retrieving a payment's details

Get the payment method and beneficiary

Check a payment's status

You can check for the status by using one of the following helper methods:

Or you can get the status as a string and compare it to the provided constants in PaymentStatus:

Working with status specific payment fields

Authorization Required Status

Payment with this status is on its initial phase where no action beyond the creation of the payment was taken.

Authorizing Status

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

Provider selection action

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.

Redirect action

This action indicates that the user needs to be redirected to complete the authorization process.

Wait action

Authorized Status

Payment has successfully completed its authorization flow

Executed Status

Payment has been accepted by the bank

Settled Status

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.

Failed Status

Payment has failed. The reason for failure can be observed in failure_reason field on the payment resource

Attempt Failed Status

Status only available when you enable payment retries.

Authorization flow config

This object provides information about the authorization flow the payment went through.

Source of funds

Cancel a payment

You can cancel a retrieved payment as long as it's not been authorised yet. Please see our documentation on payment cancellation for further details.

The cancel method returns a fresh version of the retrieved payment

Authorizing a payment

Using the Hosted Payments Page

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.

Manually starting the authorization flow

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).

Once the authorization flow has been started, refer to Authorizing payments to understand how to handle the returned actions.

Submitting a provider

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:

Refunds

Refunds are only supported for settled merchant account payments.

Creating and retrieving refunds from the client

Creating and retrieving refunds from a settled payment

Alternatively, if you already have a payment instance you can use the following convenience methods:

Payouts

Creating a payout to an external beneficiary

Creating a payout to a payment source (refunds)

Creating a payout to a preselected business account

Retrieving a payout

Merchant accounts

Listing all merchant accounts:

Retrieving an account by id:

Receiving webhook notifications

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().

Getting a webhook instance

If you already have access to a client instance, it's as easy as:

Alternatively, you can also create an instance from scratch:

Handling events

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.

Jump to supported event types

Closure handlers

Invokable classes

Supported handler types

This library supports handlers for the following event types:

• payment_authorized
• payment_executed
• payment_settled
• payment_failed
• payment_creditable
• payment_settlement_stalled
• 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.

Payment source

PaymentAuthorizedEventInterface, PaymentExecutedEventInterface, PaymentSettledEventInterface, PaymentFailedEventInterface provide a method to get more information about the payment source:

Payment method

PaymentAuthorizedEventInterface, PaymentExecutedEventInterface, PaymentSettledEventInterface, PaymentFailedEventInterface provide a method to get more information about the payment method:

Overriding globals

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.):

Signature verification failure

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

Account identifiers

All account identifiers implement a common interface, so you can access:

Based on the specific type, you can get more information:

Custom idempotency keys

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.

Custom API calls

You can use the client library to make your own API calls without worrying about authentication or request signing:

Error Handling

The client library throws the following exceptions:

PSR Exceptions

ClientExceptionInterface

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.

Custom Exceptions

All custom exceptions will extend from the base TrueLayer\Exceptions\Exception class.

ApiResponseUnsuccessfulException

Thrown if the API response is not a 2xx status.

ApiRequestJsonSerializationException

Thrown if the request data cannot be json encoded prior to calling the APIs.

InvalidArgumentException

Thrown when a provided argument is invalid, for example an invalid beneficiary type

SignerException

Thrown if the request signer cannot be initialised or signing fails.

EncryptException

Thrown when the client library fails to encrypt a payload that needs to be cached.

DecryptException

Thrown if the client library fails to decrypt the value of a cached key.

TLPublicKeysNotFound

Thrown when the webhook service cannot retrieve TL's public keys.

WebhookHandlerException

Thrown when the webhook service is provided with an invalid handler.

WebhookHandlerInvalidArgumentException

Thrown when the webhook service cannot get the request body, signature header or the provided handlers have invalid arguments.

WebhookVerificationFailedException

Thrown when the webhook signature cannot be verified.