Skip to content

Tidy Readme #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lighe wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Tidy Readme #101

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 41 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ $client = \TrueLayer\Client::configure()
->create();
```

This library assumes that your client_id is issued with the `payments` scope. Depending on your account type this may
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:

Expand All @@ -119,7 +119,7 @@ $client = \TrueLayer\Client::configure()

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](https://www.php-fig.org/psr/psr-16/) common caching interface and a 32-bytes encryption key.
the [PSR-16](https://www.php-fig.org/psr/psr-16/) common caching interface and a 32-byte 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.
Expand All @@ -146,7 +146,7 @@ $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:
You can also convert any resource to an array. This can be convenient if you need to output it to JSON, for example:

```php
$paymentData = $client->getPayment($paymentId)->toArray();
Expand Down Expand Up @@ -176,7 +176,7 @@ $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
If your merchant account is configured for payment verification, then you have the option to enable automated remitter
verification for your Merchant Account payment:

```php
Expand All @@ -192,8 +192,8 @@ $beneficiary = $client->beneficiary()
->verification($remitterVerification);
```

For your *merchant account beneficiary* you can pass a statement reference that should be set on the end user's
statement. Not all banks support setting such a reference, this value will be used wherever possible.
For your *merchant account beneficiary*, you can pass a statement reference that should be set on the end user's
statement. Not all banks support setting such a reference, but this value will be used wherever possible.

```php
$beneficiary->statementReference('Statement reference.');
Expand Down Expand Up @@ -265,7 +265,7 @@ $paymentMethod = $client->paymentMethod()->bankTransfer()
->beneficiary($beneficiary);
```

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

```php
use TrueLayer\Constants\Countries;
Expand All @@ -277,7 +277,7 @@ $filter = $client->providerFilter()
->countries([Countries::GB, Countries::ES])
->customerSegments([CustomerSegments::RETAIL, CustomerSegments::CORPORATE])
->releaseChannel(ReleaseChannels::PRIVATE_BETA)
->excludesProviderIds(['provider-id'])
->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.
Expand All @@ -297,7 +297,7 @@ $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
Alternatively, you can preselect the provider that is going to be used in the authorization flow as well as the payment
scheme that the payment is going to be sent on:

```php
Expand Down Expand Up @@ -423,7 +423,7 @@ $payment = $client->payment()->fill($paymentData)->create();

### 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,
TrueLayer's Hosted Payments 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:

```php
Expand Down Expand Up @@ -515,7 +515,7 @@ $payment->getStatus() === \TrueLayer\Constants\PaymentStatus::AUTHORIZATION_REQU

### Authorization Required Status

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

```php
use TrueLayer\Interfaces\Payment\PaymentAuthorizationRequiredInterface;
Expand All @@ -529,7 +529,7 @@ if ($payment instanceof PaymentAuthorizationRequiredInterface) {

### Authorizing Status

> Payment has its authorization_flow started, but the authorization has not completed yet
> Payment has its authorization_flow started, but the authorization has not completed yet.

A payment in `Authorizing` will expose 2 additional methods for retrieving:

Expand Down Expand Up @@ -607,7 +607,7 @@ if ($nextAction instanceof WaitActionInterface) {

### Authorized Status

> Payment has successfully completed its authorization flow
> Payment has successfully completed its authorization flow.

```php
use TrueLayer\Interfaces\Payment\PaymentAuthorizedInterface;
Expand All @@ -622,7 +622,7 @@ if ($payment instanceof PaymentAuthorizedInterface) {

### Executed Status

> Payment has been accepted by the bank
> Payment has been accepted by the bank.

```php
use TrueLayer\Interfaces\Payment\PaymentExecutedInterface;
Expand All @@ -638,7 +638,7 @@ if ($payment instanceof PaymentExecutedInterface) {

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

```php
use TrueLayer\Interfaces\Payment\PaymentSettledInterface;
Expand All @@ -656,7 +656,7 @@ if ($payment instanceof PaymentSettledInterface) {

### Failed Status

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

```php
use TrueLayer\Interfaces\Payment\PaymentFailedInterface;
Expand Down Expand Up @@ -735,10 +735,10 @@ if ($payment instanceof PaymentExecutedInterface || $payment instanceof PaymentS

# Cancel a payment

You can cancel a retrieved payment as long as it's not been authorised yet. Please see our documentation on
You can cancel a retrieved payment as long as it's not been authorized yet. Please see our documentation on
[payment cancellation](https://docs.truelayer.com/docs/cancel-a-payment) for further details.

> The `cancel` method returns a fresh version of the retrieved payment
> The `cancel` method returns a fresh version of the retrieved payment.

```php
$payment = $client->getPayment($paymentId);
Expand All @@ -752,7 +752,7 @@ $cancelledPayment = $payment->cancel();
## Using the Hosted Payments Page

You are encouraged to use our [HPP](https://docs.truelayer.com/docs/hosted-payment-page) which collects all payment
information required from your users and guides them through the payment authorisation journey. To do this simply
information required from your users and guides them through the payment authorization journey. To do this, simply
redirect to the HPP after creating a payment. See [Redirecting to HPP](#redirect-to-hpp) to get started.

## Manually starting the authorization flow
Expand Down Expand Up @@ -791,7 +791,7 @@ 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:
user selection using the `submitPaymentProvider` method:

```php
$client->submitPaymentProvider($payment, $provider);
Expand Down Expand Up @@ -855,7 +855,7 @@ $refunds = $client->getRefunds($paymentId); // RefundRetrievedInterface[]

## Creating and retrieving refunds from a settled payment

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

```php
use TrueLayer\Interfaces\Payment\PaymentSettledInterface;
Expand All @@ -873,7 +873,7 @@ if ($payment instanceof PaymentSettledInterface) {
->getId();

// Get a refund's details
$payment->getRefund($refundId)
$payment->getRefund($refundId);

// Get all refunds
$payment->getRefunds();
Expand Down Expand Up @@ -960,11 +960,10 @@ You can optionally specify the payment scheme for a payout.
```php
use \TrueLayer\Constants\SchemeIds;

$schemeSelection = $client->payoutSchemeSelection()->instantPreferred(); // Attempt to select a payment scheme that supports instant payments based on currency and geography, fallback to a non-instant scheme if instant payment is unavailable. This is used by default if no scheme selection is provided.
$schemeSelection = $client->payoutSchemeSelection()->instantPreferred(); // Attempt to select a payment scheme that supports instant payments based on currency and geography, falling back to a non-instant scheme if instant payments are unavailable. This is used by default if no scheme selection is provided.
$schemeSelection = $client->payoutSchemeSelection()->instantOnly(); // Automatically select a payment scheme that supports instant payments based on currency and geography.
$schemeSelection = $client->payoutSchemeSelection()->preselected()->schemeId(SchemeIds::FASTER_PAYMENTS_SERVICE); // Set the scheme manually. Scheme ID is required.


$client->payout()
...
->schemeSelection($schemeSelection)
Expand Down Expand Up @@ -1074,13 +1073,13 @@ $response = $client->signupPlus()
# 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](https://docs.truelayer.com/docs/set-up-truelayer-console-for-payments-v3)
webhook can be [configured in the Console](https://docs.truelayer.com/docs/set-up-truelayer-console-for-payments-v3).

> ⚠️ 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()`.
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

Expand All @@ -1095,18 +1094,18 @@ Alternatively, you can also create an instance from scratch:
```php
$webhook = \TrueLayer\Webhook::configure()
->httpClient($httpClient)
->cache($cacheImplementation, $encryptionKey) // optional, but recommeded. See Caching
->cache($cacheImplementation, $encryptionKey) // optional, but recommended. See Caching
->useProduction($useProduction) // bool
->create();
```

## 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.
have as many handlers as you wish. However, please note that 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.
interface you type-hinted in your handler.

[Jump to supported event types](#webhook-types)

Expand Down Expand Up @@ -1189,7 +1188,7 @@ This library supports handlers for the following event types:
- payout_executed
- payout_failed

You can also handle other event types by typehinting `TrueLayer\Interfaces\Webhook\EventInterface`
You can also handle other event types by type-hinting `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`.
Expand Down Expand Up @@ -1314,11 +1313,13 @@ PaymentAuthorizedEventInterface, PaymentExecutedEventInterface, PaymentSettledEv
PaymentFailedEventInterface provide a method to get more information about the payment source:

```php
$paymentSource = $event->getPaymentSource(); $paymentSource->getId(); $paymentSource->getAccountHolderName();
$paymentSource = $event->getPaymentSource();
$paymentSource->getId();
$paymentSource->getAccountHolderName();
$paymentSource->getAccountIdentifiers(); // See Account Identifiers
```

### Payment method
## Payment method

PaymentAuthorizedEventInterface, PaymentExecutedEventInterface, PaymentSettledEventInterface,
PaymentFailedEventInterface provide a method to get more information about the payment method:
Expand All @@ -1342,8 +1343,8 @@ if ($paymentMethod instanceof Webhook\PaymentMethod\MandatePaymentMethodInterfac

## 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.):
By default, the webhook service will use PHP globals to read the endpoint path and request headers and body. This
behaviour can be overridden if necessary (for example, you may be calling `execute()` in a queued job):

```php
$client->webhook()
Expand All @@ -1357,8 +1358,8 @@ behaviour can be overriden if necessary (for example you may be calling `execute
## 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](#error-handling)
A number of other exceptions will be thrown when the webhook service is misconfigured. Please
see [error handling](#error-handling).

<a name="account-identifiers"></a>

Expand Down Expand Up @@ -1488,15 +1489,15 @@ $e->getTraceId(); // The TrueLayer error trace id

### ApiRequestJsonSerializationException

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

```php
\TrueLayer\Exceptions\ApiRequestJsonSerializationException
```

### InvalidArgumentException

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

```php
\TrueLayer\Exceptions\InvalidArgumentException
Expand Down Expand Up @@ -1544,7 +1545,7 @@ 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
Thrown when the webhook service cannot get the request body, signature header, or the provided handlers have invalid
arguments.

```php
Expand Down
Loading