feature/INT-1675 - BACS Direct Debit notifications + refactor

lib/Checkout/Apm/Bacs/BacsClient.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Checkout\Apm\Bacs;
+
+use Checkout\ApiClient;
+use Checkout\AuthorizationType;
+use Checkout\CheckoutApiException;
+use Checkout\CheckoutConfiguration;
+use Checkout\Client;
+
+/**
+ * Bacs Direct Debit client.
+ */
+class BacsClient extends Client
+{
+    const APMS_PATH = "apms";
+    const BACS_PATH = "bacs";
+    const NOTIFICATIONS_PATH = "notifications";
+
+    public function __construct(ApiClient $apiClient, CheckoutConfiguration $configuration)
+    {
+        parent::__construct($apiClient, $configuration, AuthorizationType::$secretKey);
+    }
+
+    /**
+     * Sends a Bacs Direct Debit pre-notification (advance notice) to a payer ahead of collecting
+     * funds from their account.
+     *
+     * @param BacsNotificationRequest $bacsNotificationRequest
+     * @return array
+     * @throws CheckoutApiException
+     */
+    public function sendNotification(BacsNotificationRequest $bacsNotificationRequest)
+    {
+        return $this->apiClient->post(
+            $this->buildPath(self::APMS_PATH, self::BACS_PATH, self::NOTIFICATIONS_PATH),
+            $bacsNotificationRequest,
+            $this->sdkAuthorization()
+        );
+    }
+}

lib/Checkout/Apm/Bacs/BacsNotificationRequest.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace Checkout\Apm\Bacs;
+
+/**
+ * Bacs Direct Debit notification request.
+ */
+class BacsNotificationRequest
+{
+    /**
+     * The ID of the Bacs Direct Debit instrument to notify against.
+     * [Required]
+     * Pattern: ^(src)_(\w{26})$
+     * @var string
+     */
+    public $source_id;
+
+    /**
+     * The type of pre-notification being sent to the payer.
+     * [Required]
+     * @var string values of Checkout\Apm\Bacs\BacsNotificationType
+     */
+    public $notification_type;
+
+    /**
+     * The date the funds will be collected from the payer's account, in the format yyyy-MM-dd.
+     * [Required]
+     * Format: yyyy-MM-dd
+     * @var string
+     */
+    public $collection_date;
+
+    /**
+     * The amount to be collected, in the currency's minor unit.
+     * [Required]
+     * min 1
+     * @var int
+     */
+    public $amount;
+
+    /**
+     * The three-letter ISO 4217 currency code of the collection.
+     * [Required]
+     * min 3 characters, max 3 characters
+     * @var string values of Checkout\Common\Currency
+     */
+    public $currency;
+
+    /**
+     * A reference you can use to identify the collection.
+     * [Optional]
+     * max 50 characters
+     * @var string
+     */
+    public $reference;
+
+    /**
+     * The email address of the payer that the pre-notification is sent to.
+     * [Required]
+     * Format: email
+     * @var string
+     */
+    public $customer_email;
+
+    /**
+     * The billing descriptor that appears on the payer's bank statement.
+     * [Required]
+     * max 25 characters
+     * @var string
+     */
+    public $billing_descriptor;
+
+    /**
+     * The support email address included in the pre-notification.
+     * [Required]
+     * Format: email
+     * @var string
+     */
+    public $support_email;
+
+    /**
+     * The support phone number included in the pre-notification, in E.164 format.
+     * [Optional]
+     * @var string
+     */
+    public $support_phone;
+}

lib/Checkout/Apm/Bacs/BacsNotificationType.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Checkout\Apm\Bacs;
+
+/**
+ * The type of pre-notification being sent to the payer.
+ */
+class BacsNotificationType
+{
+    public static $advance_notice = "advance_notice";
+}

lib/Checkout/CheckoutApi.php

@@ -2,6 +2,7 @@
 
 namespace Checkout;
 
+use Checkout\Apm\Bacs\BacsClient;
 use Checkout\Accounts\AccountsClient;
 use Checkout\AgenticCommerce\AgenticCommerceClient;
 use Checkout\Balances\BalancesClient;
@@ -45,6 +46,7 @@ final class CheckoutApi extends CheckoutApmApi
     private $customersClient;
     private $paymentsClient;
     private $instrumentsClient;
+    private $bacsClient;
     private $forexClient;
     private $disputesClient;
     private $sessionsClient;
@@ -106,6 +108,7 @@ public function __construct(CheckoutConfiguration $configuration)
         );
         $this->paymentsClient = new PaymentsClient($baseApiClient, $configuration);
         $this->instrumentsClient = new InstrumentsClient($baseApiClient, $configuration);
+        $this->bacsClient = new BacsClient($baseApiClient, $configuration);
         $this->forexClient = new ForexClient($baseApiClient, $configuration);
         $this->disputesClient = new DisputesClient(
             $baseApiClient,
@@ -190,6 +193,19 @@ public function getInstrumentsClient()
         return $this->instrumentsClient;
     }
 
+    /**
+     * Sends Bacs Direct Debit pre-notifications.
+     *
+     * Registered here rather than on CheckoutApmApi: that class is shared with the previous
+     * platform, and POST /apms/bacs/notifications is a current-platform, secret-key-only endpoint.
+     *
+     * @return BacsClient
+     */
+    public function getBacsClient()
+    {
+        return $this->bacsClient;
+    }
+
     /**
      * @return ForexClient
      */

lib/Checkout/Common/AccountHolderSepa.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Checkout\Common;
+
+/**
+ * Account holder details for SEPA payment sources.
+ *
+ * Mirrors the `account_holder` object of the `PaymentRequestSEPAV4Source` schema - a
+ * narrower shape than {@see AccountHolder}, with only the five fields the API accepts
+ * at this position.
+ */
+class AccountHolderSepa
+{
+    /**
+     * The account holder's billing address.
+     * [Required] All five of its properties are required.
+     *
+     * @var SepaSourceBillingAddress
+     */
+    public $billing_address;
+
+    /**
+     * The account holder's first name.
+     * [Optional] max 50 characters
+     *
+     * @var string
+     */
+    public $first_name;
+
+    /**
+     * The account holder's last name.
+     * [Optional] max 50 characters
+     *
+     * @var string
+     */
+    public $last_name;
+
+    /**
+     * The account holder's company name.
+     * [Optional] max 50 characters
+     *
+     * @var string
+     */
+    public $company_name;
+
+    /**
+     * The type of account holder.
+     * [Optional]
+     *
+     * Send this lowercase (individual, corporate). The specification declares it
+     * capitalized at this one position, but every other account-holder-type position
+     * declares it lowercase and every other Checkout.com SDK sends lowercase. Pending
+     * confirmation from the API owners.
+     *
+     * @var string value of InstrumentAccountHolderType
+     */
+    public $type;
+}

lib/Checkout/Common/AchSourceAccountType.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Checkout\Common;
+
+/**
+ * The type of Direct Debit account on an ACH payment source.
+ *
+ * `PaymentRequestAchSource` is the only schema declaring this set of values. Two
+ * neighbouring types are deliberately different and are not interchangeable:
+ *
+ * - {@see AccountType} is savings / current / cash and serves the bank-account
+ *   instrument and destination positions, so it cannot express `checking`.
+ * - {@see \Checkout\Instruments\AchAccountType} is savings / checking and serves the
+ *   stored ACH instrument positions, so it does not declare `cash`.
+ */
+class AchSourceAccountType
+{
+    public static $savings = "savings";
+    public static $checking = "checking";
+    public static $cash = "cash";
+}

lib/Checkout/Common/InstrumentType.php

@@ -2,6 +2,12 @@
 
 namespace Checkout\Common;
 
+/**
+ * The type of payment instrument.
+ *
+ * The current API declares bacs, bank_account, card, token, sepa and ach. This class also carries
+ * card_token, which only the previous API (ABC) accepts.
+ */
 class InstrumentType
 {
     public static $bank_account = "bank_account";
@@ -12,5 +18,17 @@ class InstrumentType
 
     public static $sepa = "sepa";
 
+    public static $ach = "ach";
+
+    public static $bacs = "bacs";
+
+    // ========================================
+    // Previous API (ABC) only - not declared by the current API (NAS)
+    // ========================================
+
+    /**
+     * <b>Previous API (ABC) only.</b> The current API's instrument type does not declare this value.
+     * Only use it when working with Previous API accounts.
+     */
     public static $card_token = "card_token";
 }

lib/Checkout/Common/PaymentSourceType.php

@@ -2,6 +2,19 @@
 
 namespace Checkout\Common;
 
+/**
+ * The payment source type.
+ *
+ * This class is the union of the source types accepted on payment requests and returned on payment
+ * responses, on both the current API (NAS) and the previous API (ABC). 42 of the values below are
+ * declared by the current API's PaymentRequestSourceType or PaymentDetailsResponseSourceType.
+ *
+ * <b>Previous API (ABC) only</b> - the current API does not declare these 18 and will reject them:
+ * afterpay, alipay, bank_account, benefit, benefitpay, boleto, cvconnect, dlocal, giropay,
+ * illicado, oxxo, pagofacil, poli, postfinance, provider_token, rapipago, sofort, trustly.
+ * They are interleaved with the current values below rather than grouped, which is historical; the
+ * ordering is not reworked here because these properties are referenced across the SDK.
+ */
 class PaymentSourceType
 {
     public static $card = "card";
@@ -51,6 +64,8 @@ class PaymentSourceType
     public static $alma = "alma";
     public static $trustly = "trustly";
     public static $cvconnect = "cvconnect";
+    public static $bacs = "bacs";
+
     public static $sepa = "sepa";
     public static $bizum = "bizum";
     public static $ach = "ach";

lib/Checkout/Common/SepaSourceBillingAddress.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Checkout\Common;
+
+/**
+ * The account holder's billing address on a SEPA payment source.
+ *
+ * Mirrors the `billing_address` object of `PaymentRequestSEPAV4Source.account_holder`,
+ * where every property is required. Deliberately not {@see Address}, which also
+ * declares `state` - a property this position does not accept.
+ */
+class SepaSourceBillingAddress
+{
+    /**
+     * The account holder's street name.
+     * [Required]
+     *
+     * @var string
+     */
+    public $address_line1;
+
+    /**
+     * The account holder's street number.
+     * [Required] max 10 characters
+     *
+     * @var string
+     */
+    public $address_line2;
+
+    /**
+     * The account holder's city.
+     * [Required] max 35 characters
+     *
+     * @var string
+     */
+    public $city;
+
+    /**
+     * The account holder's zip code.
+     * [Required] max 16 characters
+     *
+     * @var string
+     */
+    public $zip;
+
+    /**
+     * The account holder's country, as an ISO 3166-1 alpha-2 code.
+     * [Required] max 2 characters
+     *
+     * @var string value of Country
+     */
+    public $country;
+}

lib/Checkout/Instruments/AchAccountType.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Checkout\Instruments;
+
+/**
+ * The type of Direct Debit account of an ACH instrument.
+ *
+ * Shared by the store, update and retrieve ACH instrument variants, which all declare the same two
+ * values. Do not use Checkout\Common\AccountType, which declares savings, current and cash.
+ */
+class AchAccountType
+{
+    public static $savings = "savings";
+
+    public static $checking = "checking";
+}