[ACL-133] Add support for retry object on payment method (#56)

Author: lighe

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2024-07-15
+
+### Added
+
+- Support for `retry` object on bank transfer payment method
+
 ## [2.1.0] - 2024-05-16
 
 ### Added

README.md

@@ -266,6 +266,14 @@ $paymentMethod = $client->paymentMethod()->bankTransfer()
     ->providerSelection($providerSelection);
 ```
 
+You can also enable payment retries, but make sure you can handle the `attempt_failed` payment status beforehand:
+
+```php
+$paymentMethod = $client->paymentMethod()->bankTransfer()
+    ->enablePaymentRetry()
+    ->beneficiary($beneficiary);
+```
+
 <a name="creating-the-payment"></a>
 
 ### 4. Creating the payment

src/Entities/Payment/PaymentMethod/BankTransferPaymentMethod.php

@@ -4,6 +4,7 @@
 
 namespace TrueLayer\Entities\Payment\PaymentMethod;
 
+use stdClass;
 use TrueLayer\Constants\PaymentMethods;
 use TrueLayer\Entities\Entity;
 use TrueLayer\Exceptions\InvalidArgumentException;
@@ -29,12 +30,18 @@ class BankTransferPaymentMethod extends Entity implements BankTransferPaymentMet
      */
     protected ProviderSelectionInterface $providerSelection;
 
+    /**
+     * @var stdClass|null
+     */
+    protected ?stdClass $retry;
+
     /**
      * @var string[]
      */
     protected array $casts = [
         'provider_selection' => ProviderSelectionInterface::class,
         'beneficiary' => BeneficiaryInterface::class,
+        'retry' => stdClass::class,
     ];
 
     /**
@@ -44,6 +51,7 @@ class BankTransferPaymentMethod extends Entity implements BankTransferPaymentMet
         'type',
         'beneficiary',
         'provider_selection',
+        'retry',
     ];
 
     /**
@@ -79,15 +87,32 @@ public function providerSelection(ProviderSelectionInterface $providerSelection)
     }
 
     /**
+     * @return ProviderSelectionInterface
      * @throws InvalidArgumentException
      *
-     * @return ProviderSelectionInterface
      */
     public function getProviderSelection(): ProviderSelectionInterface
     {
         return $this->providerSelection ?? $this->make(UserSelectedProviderSelectionInterface::class);
     }
 
+    /**
+     * @return BankTransferPaymentMethodInterface
+     */
+    public function enablePaymentRetry(): BankTransferPaymentMethodInterface
+    {
+        $this->retry = new stdClass();
+
+        return $this;
+    }
+
+    public function isPaymentRetryEnabled(): bool
+    {
+        $retry = $this->retry ?? null;
+
+        return !!$retry;
+    }
+
     /**
      * @return string
      */

src/Interfaces/PaymentMethod/BankTransferPaymentMethodInterface.php

@@ -32,4 +32,14 @@ public function providerSelection(ProviderSelectionInterface $providerSelection)
      * @return ProviderSelectionInterface
      */
     public function getProviderSelection(): ProviderSelectionInterface;
+
+    /**
+     * @return BankTransferPaymentMethodInterface
+     */
+    public function enablePaymentRetry(): BankTransferPaymentMethodInterface;
+
+    /**
+     * @return bool
+     */
+    public function isPaymentRetryEnabled(): bool;
 }

src/Traits/CastsAttributes.php

@@ -26,12 +26,12 @@ protected function casts(): array
     }
 
     /**
-     * @param mixed[]      $data
+     * @param mixed[] $data
      * @param mixed[]|null $casts
      *
+     * @return mixed[]
      * @throws InvalidArgumentException
      *
-     * @return mixed[]
      */
     protected function castData(array $data, array $casts = null): array
     {
@@ -74,6 +74,8 @@ protected function castData(array $data, array $casts = null): array
                         if (\is_string($partData)) {
                             $partData = $this->toDateTime($partData);
                         }
+                    } elseif ($abstract === \stdClass::class) {
+                        $partData = (object)$partData;
                     } elseif (\is_array($partData) && \is_string($abstract) && (\interface_exists($abstract) || \class_exists($abstract))) {
                         // @phpstan-ignore-next-line
                         $partData = $this->make($abstract, $partData);
@@ -108,11 +110,11 @@ protected function toDateTime(string $dateTime): ?\DateTimeInterface
      * @template T
      *
      * @param class-string<T> $abstract
-     * @param mixed[]|null    $data
+     * @param mixed[]|null $data
      *
+     * @return T
      * @throws InvalidArgumentException
      *
-     * @return T
      */
     abstract protected function make(string $abstract, array $data = null);
 }

tests/acceptance/Payment/MerchantAccountPaymentAuthorizationTest.php

@@ -37,13 +37,36 @@
     \expect($created->getResourceToken())->toBeString();
     \expect($created->getUserId())->toBeString();
 
+    /** @var BankTransferPaymentMethodInterface $paymentMethod */
     $paymentMethod = $created->getDetails()->getPaymentMethod();
     \expect($paymentMethod)->toBeInstanceOf(BankTransferPaymentMethodInterface::class);
     \expect($paymentMethod->getBeneficiary()->getReference())->toBe('TEST');
+    \expect($paymentMethod->isPaymentRetryEnabled())->toBe(false);
 
     return $created;
 });
 
+\it('creates a merchant payment with retry enabled', function () {
+    $helper = \paymentHelper();
+
+    $account = Arr::first(
+        $helper->client()->getMerchantAccounts(),
+        fn(MerchantAccountInterface $account) => $account->getCurrency() === 'GBP'
+    );
+
+    $merchantBeneficiary = $helper->merchantBeneficiary($account);
+
+    $created = $helper->create(
+        $helper->bankTransferMethod($merchantBeneficiary)->enablePaymentRetry(), $helper->user(), $account->getCurrency()
+    );
+
+    \expect($created)->toBeInstanceOf(PaymentCreatedInterface::class);
+
+    /** @var BankTransferPaymentMethodInterface $paymentMethod */
+    $paymentMethod = $created->getDetails()->getPaymentMethod();
+    \expect($paymentMethod->isPaymentRetryEnabled())->toBe(true);
+});
+
 \it('starts payment authorization', function (PaymentCreatedInterface $created) {
     $response = \client()->startPaymentAuthorization($created, 'https://console.truelayer.com/redirect-page');
 

tests/integration/Mocks/PaymentResponse.php

@@ -29,6 +29,11 @@ public static function authorizationRequired(): Response
         return new Response(200, [], '{"id":"56bbff85-9504-4cba-a63b-c781745ad3ed","amount_in_minor":1,"metadata":{"metadata_key_1":"metadata_value_1","metadata_key_2":"metadata_value_2","metadata_key_3":"metadata_value_3"},"currency":"GBP","user":{"id":"c4e754fd-8b0d-40fe-bd61-36622b7477a4"},"payment_method":{"type":"bank_transfer","beneficiary":{"type":"external_account","account_identifier":{"type":"sort_code_account_number","sort_code":"010203","account_number":"12345678"},"account_holder_name":"Bob","reference":"TEST"},"provider_selection":{"type":"user_selected"}},"created_at":"2022-02-04T13:40:23.798415Z","status":"authorization_required"}');
     }
 
+    public static function authorizationRequiredWithRetryField(): Response
+    {
+        return new Response(200, [], '{"id":"56bbff85-9504-4cba-a63b-c781745ad3ed","amount_in_minor":1,"metadata":{"metadata_key_1":"metadata_value_1","metadata_key_2":"metadata_value_2","metadata_key_3":"metadata_value_3"},"currency":"GBP","user":{"id":"c4e754fd-8b0d-40fe-bd61-36622b7477a4"},"payment_method":{"type":"bank_transfer","retry":{},"beneficiary":{"type":"external_account","account_identifier":{"type":"sort_code_account_number","sort_code":"010203","account_number":"12345678"},"account_holder_name":"Bob","reference":"TEST"},"provider_selection":{"type":"user_selected"}},"created_at":"2022-02-04T13:40:23.798415Z","status":"authorization_required"}');
+    }
+
     public static function authorizingProviderSelection(): Response
     {
         return new Response(200, [], '{"id":"56bbff85-9504-4cba-a63b-c781745ad3ed","amount_in_minor":1,"metadata":{"metadata_key_1":"metadata_value_1","metadata_key_2":"metadata_value_2","metadata_key_3":"metadata_value_3"},"currency":"GBP","user":{"id":"c4e754fd-8b0d-40fe-bd61-36622b7477a4"},"payment_method":{"type":"bank_transfer","beneficiary":{"type":"external_account","account_identifier":{"type":"sort_code_account_number","sort_code":"010203","account_number":"12345678"},"account_holder_name":"Bob","reference":"TEST"},"provider_selection":{"type":"user_selected"}},"created_at":"2022-02-04T13:40:23.798415Z","status":"authorizing","authorization_flow":{"actions":{"next":{"type":"provider_selection","providers":[{"id":"mock-payments-gb-redirect","display_name":"Mock UK Payments - Redirect Flow","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/icons/mock-payments-gb-redirect.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/logos/mock-payments-gb-redirect.svg","bg_color":"#FFFFFF","country_code":"GB"},{"id":"oauth-starling","display_name":"Starling","icon_uri":"https://truelayer-client-logos.s3-eu-west-1.amazonaws.com/banks/banks-icons/oauth-starling-icon.svg","logo_uri":"https://truelayer-client-logos.s3-eu-west-1.amazonaws.com/banks/oauth-starling.svg","bg_color":"#007EB6","country_code":"GB"},{"id":"ob-barclays","display_name":"Barclays","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/barclays.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/barclays.svg","bg_color":"#007EB6","country_code":"GB"},{"id":"ob-boi","display_name":"Bank of Ireland UK","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/boi.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/boi.svg","bg_color":"#125B84","country_code":"GB"},{"id":"ob-bos","display_name":"Bank of Scotland","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/icons/bos.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/logos/bos.svg","bg_color":"#05286a","country_code":"GB"},{"id":"ob-danske","display_name":"Danske Bank","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/danske.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/danske.svg","bg_color":"#003755","country_code":"GB"},{"id":"ob-first-direct","display_name":"first direct","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/icons/first-direct.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/logos/first-direct.svg","bg_color":"#626268","country_code":"GB"},{"id":"ob-halifax","display_name":"Halifax","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/icons/halifax.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/logos/halifax.svg","bg_color":"#0040bb","country_code":"GB"},{"id":"ob-hsbc","display_name":"HSBC","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/hsbc.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/hsbc.svg","bg_color":"#515358","country_code":"GB"},{"id":"ob-lloyds","display_name":"Lloyds","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/lloyds.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/lloyds.svg","bg_color":"#00553e","country_code":"GB"},{"id":"ob-monzo","display_name":"Monzo","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/monzo.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/monzo.svg","bg_color":"#15233c","country_code":"GB"},{"id":"ob-nationwide","display_name":"Nationwide","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/icons/nationwide.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/logos/nationwide.svg","bg_color":"#002878","country_code":"GB"},{"id":"ob-natwest","display_name":"NatWest","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/natwest.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/natwest.svg","bg_color":"#42145f","country_code":"GB"},{"id":"ob-rbs","display_name":"Royal Bank of Scotland","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/rbs.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/rbs.svg","bg_color":"#0A2F64","country_code":"GB"},{"id":"ob-revolut","display_name":"Revolut","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/revolut.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/revolut.svg","bg_color":"#0067EA","country_code":"GB"},{"id":"ob-santander","display_name":"Santander","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/santander.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/santander.svg","bg_color":"#EC0000","country_code":"GB"},{"id":"ob-tesco","display_name":"Tesco Bank","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/icons/tesco.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/logos/tesco.svg","bg_color":"#1b3160","country_code":"GB"},{"id":"ob-tsb","display_name":"TSB","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/icons/tsb.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/uk/logos/tsb.svg","bg_color":"#007BC3","country_code":"GB"},{"id":"ob-uki-mock-bank","display_name":"UKI Mock Bank","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/generic.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic.svg","bg_color":"","country_code":"GB"},{"id":"ob-ulster","display_name":"Ulster Bank","icon_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/icons/ulster.svg","logo_uri":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/ulster.svg","bg_color":"#0a2f64","country_code":"GB"}]}},"configuration":{"provider_selection":{},"redirect":{"return_uri":"https://penny.t7r.dev/redirect/v3"}}}}');

tests/integration/PaymentCreateTest.php

@@ -54,6 +54,7 @@
                 ],
                 'scheme_selection' => null,
             ],
+            'retry' => null,
         ],
     ]);
 });
@@ -203,6 +204,24 @@
     ]);
 });
 
+\it('does not send retry field', function () {
+    $factory = CreatePayment::responses([PaymentResponse::created()]);
+    $factory->payment($factory->newUser(), $factory->bankTransferMethod($factory->sortCodeBeneficiary()))->create();
+
+    $payload = json_decode(\getRequestPayload(1, false), false);
+    expect($payload->payment_method->retry)->toBeNull();
+});
+
+\it('sends retry field', function () {
+    $factory = CreatePayment::responses([PaymentResponse::created()]);
+    $method = $factory->bankTransferMethod($factory->sortCodeBeneficiary())->enablePaymentRetry();
+    $factory->payment($factory->newUser(), $method)->create();
+
+    $payload = json_decode(\getRequestPayload(1, false), false);
+
+    expect($payload->payment_method->retry)->toBeInstanceOf(stdClass::class);
+});
+
 \it('parses payment creation response correctly', function () {
     $factory = CreatePayment::responses([PaymentResponse::created()]);
     $payment = $factory->payment($factory->newUser(), $factory->bankTransferMethod($factory->sortCodeBeneficiary()))->create();

tests/integration/PaymentRetrievalTest.php

@@ -282,9 +282,9 @@ function assertPaymentCommon(PaymentRetrievedInterface $payment)
     $providerSelection = $method->getProviderSelection();
     $schemeSelection = $providerSelection->getSchemeSelection();
 
-
     \expect($schemeSelection)->toBeInstanceOf($expectedType);
     \expect($schemeSelection->getType())->toBe($expectedTypeValue);
+
     if ($expectedAllowedRemitterFee !== null) {
         /** @var InstantSchemeSelectionInterface $selection */
         $selection = $schemeSelection;
@@ -309,3 +309,16 @@ function assertPaymentCommon(PaymentRetrievedInterface $payment)
         'expectedAllowedRemitterFee' => true,
     ]
 ]);
+
+it('handles retry field correctly - empty object serialisation', function () {
+    $payment1 = \client(PaymentResponse::authorizationRequiredWithRetryField())->getPayment('1');
+    /** @var BankTransferPaymentMethodInterface $method */
+    $method1 = $payment1->getPaymentMethod();
+
+    $payment2 = \client(PaymentResponse::authorizationRequired())->getPayment('1');
+    /** @var BankTransferPaymentMethodInterface $method */
+    $method2 = $payment2->getPaymentMethod();
+
+    expect($method1->isPaymentRetryEnabled())->toBe(true);
+    expect($method2->isPaymentRetryEnabled())->toBe(false);
+});