Merge pull request #146 from gocardless/template-changes

Add `mandate_request[description]` and `mandate_request[constraints]` parameters to Billing Request creation

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "gocardless/gocardless-pro",
   "description": "GoCardless Pro PHP Client Library",
-  "version": "4.20.0",
+  "version": "4.21.0",
   "keywords": [
     "gocardless",
     "direct debit",

lib/Client.php

@@ -57,7 +57,7 @@ public function __construct($config)
                 'Content-Type' => 'application/json',
                 'Authorization' => "Bearer " . $access_token,
                 'GoCardless-Client-Library' => 'gocardless-pro-php',
-                'GoCardless-Client-Version' => '4.20.0',
+                'GoCardless-Client-Version' => '4.21.0',
                 'User-Agent' => $this->getUserAgent()
                 ),
                 'http_errors' => false,
@@ -337,6 +337,20 @@ public function mandatePdfs()
         return $this->mandate_pdfs;
     }
 
+    /**
+     * Service for interacting with mandate request constraints
+     *
+     * @return Services\MandateRequestConstraintsService
+     */
+    public function mandateRequestConstraints()
+    {
+        if (!isset($this->mandate_request_constraints)) {
+            $this->mandate_request_constraints = new Services\MandateRequestConstraintsService($this->api_client);
+        }
+
+        return $this->mandate_request_constraints;
+    }
+
     /**
      * Service for interacting with payer authorisations
      *
@@ -526,7 +540,7 @@ private function getUserAgent()
     {
         $curlinfo = curl_version();
         $uagent = array();
-        $uagent[] = 'gocardless-pro-php/4.20.0';
+        $uagent[] = 'gocardless-pro-php/4.21.0';
         $uagent[] = 'schema-version/2015-07-06';
         if (defined('\GuzzleHttp\Client::MAJOR_VERSION')) {
             $uagent[] = 'GuzzleHttp/' . \GuzzleHttp\Client::MAJOR_VERSION;

lib/Resources/BillingRequestTemplate.php

@@ -15,6 +15,7 @@
  * @property-read $created_at
  * @property-read $id
  * @property-read $mandate_request_currency
+ * @property-read $mandate_request_description
  * @property-read $mandate_request_metadata
  * @property-read $mandate_request_scheme
  * @property-read $mandate_request_verify
@@ -55,6 +56,12 @@ class BillingRequestTemplate extends BaseResource
      */
     protected $mandate_request_currency;
 
+    /**
+     * A human-readable description of the payment and/or mandate. This will be
+     * displayed to the payer when authorising the billing request.
+     */
+    protected $mandate_request_description;
+
     /**
      * Key-value store of custom data that will be applied to the mandate
      * created when this request is fulfilled. Up to 3 keys are permitted, with
@@ -63,8 +70,11 @@ class BillingRequestTemplate extends BaseResource
     protected $mandate_request_metadata;
 
     /**
-     * A Direct Debit scheme. Currently "ach", "bacs", "becs", "becs_nz",
-     * "betalingsservice", "pad", "pay_to" and "sepa_core" are supported.
+     * A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs",
+     * "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to" and
+     * "sepa_core" are supported. Optional for mandate only requests - if left
+     * blank, the payer will be able to select the currency/scheme to pay with
+     * from a list of your available schemes.
      */
     protected $mandate_request_scheme;
 
@@ -122,8 +132,8 @@ class BillingRequestTemplate extends BaseResource
     protected $payment_request_currency;
 
     /**
-     * A human-readable description of the payment. This will be displayed to
-     * the payer when authorising the billing request.
+     * A human-readable description of the payment and/or mandate. This will be
+     * displayed to the payer when authorising the billing request.
      */
     protected $payment_request_description;
 

lib/Resources/Creditor.php

@@ -11,6 +11,7 @@
  * A thin wrapper around a creditor, providing access to its
  * attributes
  *
+ * @property-read $activated
  * @property-read $address_line1
  * @property-read $address_line2
  * @property-read $address_line3
@@ -35,6 +36,12 @@ class Creditor extends BaseResource
 {
     protected $model_name = "Creditor";
 
+    /**
+     * Boolean value indicating whether the creditor is activated in the
+     * product.
+     */
+    protected $activated;
+
     /**
      * The first line of the creditor's address.
      */
@@ -74,7 +81,7 @@ class Creditor extends BaseResource
 
     /**
      * Boolean value indicating whether creditor has the [Custom Payment
-     * Pages](https://support.gocardless.com/hc/en-gb/articles/115003734705-Custom-payment-pages)
+     * Pages](https://hub.gocardless.com/s/article/Custom-payment-pages)
      * functionality enabled.
      */
     protected $custom_payment_pages_enabled;

lib/Resources/Mandate.php

@@ -11,6 +11,7 @@
  * A thin wrapper around a mandate, providing access to its
  * attributes
  *
+ * @property-read $consent_parameters
  * @property-read $created_at
  * @property-read $id
  * @property-read $links
@@ -25,6 +26,11 @@ class Mandate extends BaseResource
 {
     protected $model_name = "Mandate";
 
+    /**
+     * (Optional) Payto and VRP Scheme specific information
+     */
+    protected $consent_parameters;
+
     /**
      * Fixed [timestamp](#api-usage-time-zones--dates), recording when this
      * resource was created.
@@ -69,7 +75,7 @@ class Mandate extends BaseResource
     protected $reference;
 
     /**
-     * <a name="mandates_scheme"></a>Direct Debit scheme to which this mandate
+     * <a name="mandates_scheme"></a>Bank payment scheme to which this mandate
      * and associated payments are submitted. Can be supplied or automatically
      * detected from the customer's bank account.
      */

lib/Resources/MandateRequestConstraints.php

@@ -0,0 +1,54 @@
+<?php
+/**
+ * WARNING: Do not edit by hand, this file was generated by Crank:
+ *
+ * https://github.com/gocardless/crank
+ */
+
+namespace GoCardlessPro\Resources;
+
+/**
+ * A thin wrapper around a mandate_request_constraints, providing access to its
+ * attributes
+ *
+ * @property-read $end_date
+ * @property-read $max_amount_per_payment
+ * @property-read $periodic_limits
+ * @property-read $start_date
+ */
+class MandateRequestConstraints extends BaseResource
+{
+    protected $model_name = "MandateRequestConstraints";
+
+    /**
+     * The latest date at which payments can be taken, must occur after
+     * start_date if present
+     * 
+     * This is an optional field and if it is not supplied the agreement will be
+     * considered open and
+     * will not have an end date. Keep in mind the end date must take into
+     * account how long it will
+     * take the user to set up this agreement via the BillingRequest.
+     */
+    protected $end_date;
+
+    /**
+     * The maximum amount that can be charged for a single payment
+     */
+    protected $max_amount_per_payment;
+
+    /**
+     * List of periodic limits and constraints which apply to them
+     */
+    protected $periodic_limits;
+
+    /**
+     * The date from which payments can be taken.
+     * 
+     * This is an optional field and if it is not supplied the start date will
+     * be set to the day
+     * authorisation happens.
+     */
+    protected $start_date;
+
+}

lib/Resources/Payment.php

@@ -99,6 +99,7 @@ class Payment extends BaseResource
      * characters<br /> <strong>Bacs</strong> - 10 characters<br />
      * <strong>BECS</strong> - 30 characters<br /> <strong>BECS NZ</strong> - 12
      * characters<br /> <strong>Betalingsservice</strong> - 30 characters<br />
+     * <strong>Faster Payments</strong> - 18 characters<br />
      * <strong>PAD</strong> - scheme doesn't offer references<br />
      * <strong>PayTo</strong> - 18 characters<br /> <strong>SEPA</strong> - 140
      * characters<br /> Note that this reference must be unique (for each
@@ -107,7 +108,9 @@ class Payment extends BaseResource
      * specify a payment reference for Bacs payments (that is, when collecting
      * from the UK) if you're on the <a
      * href='https://gocardless.com/pricing'>GoCardless Plus, Pro or Enterprise
-     * packages</a>.</p>
+     * packages</a>.</p> <p
+     * class='restricted-notice'><strong>Restricted</strong>: You can not
+     * specify a payment reference for Faster Payments.</p>
      */
     protected $reference;
 

lib/Resources/Payout.php

@@ -92,7 +92,8 @@ class Payout extends BaseResource
 
     /**
      * Key-value store of custom data. Up to 3 keys are permitted, with key
-     * names up to 50 characters and values up to 500 characters.
+     * names up to 50 characters and values up to 500 characters. _Note:_ This
+     * should not be used for storing PII data.
      */
     protected $metadata;
 

lib/Resources/PayoutItem.php

@@ -43,8 +43,7 @@ class PayoutItem extends BaseResource
      * An array of tax items <em>beta</em>
      * 
      * _Note_: VAT applies to transaction and surcharge fees for merchants
-     * operating in the <a href="https://gocardless.com/legal/vat-faqs">UK</a>
-     * and <a href="https://gocardless.com/fr-fr/legal/faq-tva">France</a>.
+     * operating in the UK and France.
      */
     protected $taxes;
 

lib/Resources/RedirectFlow.php

@@ -69,7 +69,8 @@ class RedirectFlow extends BaseResource
 
     /**
      * Key-value store of custom data. Up to 3 keys are permitted, with key
-     * names up to 50 characters and values up to 500 characters.
+     * names up to 50 characters and values up to 500 characters. _Note:_ This
+     * should not be used for storing PII data.
      */
     protected $metadata;
 

lib/Resources/Refund.php

@@ -71,6 +71,7 @@ class Refund extends BaseResource
      * characters<br /> <strong>Bacs</strong> - 10 characters<br />
      * <strong>BECS</strong> - 30 characters<br /> <strong>BECS NZ</strong> - 12
      * characters<br /> <strong>Betalingsservice</strong> - 30 characters<br />
+     * <strong>Faster Payments</strong> - 18 characters<br />
      * <strong>PAD</strong> - scheme doesn't offer references<br />
      * <strong>PayTo</strong> - 18 characters<br /> <strong>SEPA</strong> - 140
      * characters<br /> Note that this reference must be unique (for each
@@ -79,7 +80,9 @@ class Refund extends BaseResource
      * specify a payment reference for Bacs payments (that is, when collecting
      * from the UK) if you're on the <a
      * href='https://gocardless.com/pricing'>GoCardless Plus, Pro or Enterprise
-     * packages</a>.</p>
+     * packages</a>.</p> <p
+     * class='restricted-notice'><strong>Restricted</strong>: You can not
+     * specify a payment reference for Faster Payments.</p>
      */
     protected $reference;
 

lib/Resources/ScenarioSimulator.php

@@ -111,6 +111,10 @@ class ScenarioSimulator extends BaseResource
      * GoCardless to change their bank details. It must start in the
      * `pending_submission` state. Only compatible with Bacs, SEPA and Autogiro
      * mandates.</li>
+     * <li>`mandate_suspended_by_payer`: Transitions a mandate to
+     * `suspended_by_payer`, as if payer has suspended the mandate after it has
+     * been setup successfully. It must start in the `activated` state. Only
+     * compatible with PAY_TO mandates.</li>
      * <li>`refund_paid`: Transitions a refund to `paid`. It must start in
      * either the `pending_submission` or `submitted` state.</li>
      * <li>`refund_settled`: Transitions a refund to `paid`, if it's not

lib/Services/MandateRequestConstraintsService.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * WARNING: Do not edit by hand, this file was generated by Crank:
+ *
+ * https://github.com/gocardless/crank
+ */
+
+namespace GoCardlessPro\Services;
+
+use \GoCardlessPro\Core\Paginator;
+use \GoCardlessPro\Core\Util;
+use \GoCardlessPro\Core\ListResponse;
+use \GoCardlessPro\Resources\MandateRequestConstraints;
+use \GoCardlessPro\Core\Exception\InvalidStateException;
+
+
+/**
+ * Service that provides access to the MandateRequestConstraints
+ * endpoints of the API
+ */
+class MandateRequestConstraintsService extends BaseService
+{
+
+    protected $envelope_key   = 'mandate_request_constraints';
+    protected $resource_class = '\GoCardlessPro\Resources\MandateRequestConstraints';
+
+
+}

lib/Services/ScenarioSimulatorsService.php

@@ -144,6 +144,11 @@ class ScenarioSimulatorsService extends BaseService
  change their bank details. It must start in the
  `pending_submission` state. Only compatible with Bacs, SEPA
  and Autogiro mandates.</li>
+ <li>`mandate_suspended_by_payer`: Transitions a mandate to
+ `suspended_by_payer`, as if payer has suspended the mandate
+ after it has been setup successfully. It must start in the
+ `activated` state. Only compatible with PAY_TO
+ mandates.</li>
  <li>`refund_paid`: Transitions a refund to `paid`. It must
  start in either the `pending_submission` or `submitted`
  state.</li>

tests/Integration/BillingRequestTemplatesIntegrationTest.php

@@ -39,6 +39,7 @@ public function testBillingRequestTemplatesList()
             $this->assertEquals($body[$num]->created_at, $record->created_at);
             $this->assertEquals($body[$num]->id, $record->id);
             $this->assertEquals($body[$num]->mandate_request_currency, $record->mandate_request_currency);
+            $this->assertEquals($body[$num]->mandate_request_description, $record->mandate_request_description);
             $this->assertEquals($body[$num]->mandate_request_metadata, $record->mandate_request_metadata);
             $this->assertEquals($body[$num]->mandate_request_scheme, $record->mandate_request_scheme);
             $this->assertEquals($body[$num]->mandate_request_verify, $record->mandate_request_verify);
@@ -76,6 +77,7 @@ public function testBillingRequestTemplatesGet()
         $this->assertEquals($body->created_at, $response->created_at);
         $this->assertEquals($body->id, $response->id);
         $this->assertEquals($body->mandate_request_currency, $response->mandate_request_currency);
+        $this->assertEquals($body->mandate_request_description, $response->mandate_request_description);
         $this->assertEquals($body->mandate_request_metadata, $response->mandate_request_metadata);
         $this->assertEquals($body->mandate_request_scheme, $response->mandate_request_scheme);
         $this->assertEquals($body->mandate_request_verify, $response->mandate_request_verify);
@@ -112,6 +114,7 @@ public function testBillingRequestTemplatesCreate()
         $this->assertEquals($body->created_at, $response->created_at);
         $this->assertEquals($body->id, $response->id);
         $this->assertEquals($body->mandate_request_currency, $response->mandate_request_currency);
+        $this->assertEquals($body->mandate_request_description, $response->mandate_request_description);
         $this->assertEquals($body->mandate_request_metadata, $response->mandate_request_metadata);
         $this->assertEquals($body->mandate_request_scheme, $response->mandate_request_scheme);
         $this->assertEquals($body->mandate_request_verify, $response->mandate_request_verify);
@@ -155,6 +158,7 @@ public function testBillingRequestTemplatesCreateWithIdempotencyConflict()
         $this->assertEquals($body->created_at, $response->created_at);
         $this->assertEquals($body->id, $response->id);
         $this->assertEquals($body->mandate_request_currency, $response->mandate_request_currency);
+        $this->assertEquals($body->mandate_request_description, $response->mandate_request_description);
         $this->assertEquals($body->mandate_request_metadata, $response->mandate_request_metadata);
         $this->assertEquals($body->mandate_request_scheme, $response->mandate_request_scheme);
         $this->assertEquals($body->mandate_request_verify, $response->mandate_request_verify);
@@ -192,6 +196,7 @@ public function testBillingRequestTemplatesUpdate()
         $this->assertEquals($body->created_at, $response->created_at);
         $this->assertEquals($body->id, $response->id);
         $this->assertEquals($body->mandate_request_currency, $response->mandate_request_currency);
+        $this->assertEquals($body->mandate_request_description, $response->mandate_request_description);
         $this->assertEquals($body->mandate_request_metadata, $response->mandate_request_metadata);
         $this->assertEquals($body->mandate_request_scheme, $response->mandate_request_scheme);
         $this->assertEquals($body->mandate_request_verify, $response->mandate_request_verify);