Merge pull request #133 from gocardless/template-changes

4.16.0

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "gocardless/gocardless-pro",
   "description": "GoCardless Pro PHP Client Library",
-  "version": "4.15.0",
+  "version": "4.16.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.15.0',
+                'GoCardless-Client-Version' => '4.16.0',
                 'User-Agent' => $this->getUserAgent()
                 ),
                 'http_errors' => false,
@@ -526,7 +526,7 @@ private function getUserAgent()
     {
         $curlinfo = curl_version();
         $uagent = array();
-        $uagent[] = 'gocardless-pro-php/4.15.0';
+        $uagent[] = 'gocardless-pro-php/4.16.0';
         $uagent[] = 'schema-version/2015-07-06';
         if (defined('\GuzzleHttp\Client::MAJOR_VERSION')) {
             $uagent[] = 'GuzzleHttp/' . \GuzzleHttp\Client::MAJOR_VERSION;

lib/Resources/BillingRequest.php

@@ -13,6 +13,7 @@
  *
  * @property-read $actions
  * @property-read $created_at
+ * @property-read $fallback_enabled
  * @property-read $id
  * @property-read $links
  * @property-read $mandate_request
@@ -37,6 +38,12 @@ class BillingRequest extends BaseResource
      */
     protected $created_at;
 
+    /**
+     * If true, this billing request can fallback from instant payment to direct
+     * debit.
+     */
+    protected $fallback_enabled;
+
     /**
      * Unique identifier, beginning with "BRQ".
      */
@@ -71,11 +78,11 @@ class BillingRequest extends BaseResource
     /**
      * One of:
      * <ul>
-     * <li>`pending`: the billing_request is pending and can be used</li>
-     * <li>`ready_to_fulfil`: the billing_request is ready to fulfil</li>
-     * <li>`fulfilled`: the billing_request has been fulfilled and a payment
+     * <li>`pending`: the billing request is pending and can be used</li>
+     * <li>`ready_to_fulfil`: the billing request is ready to fulfil</li>
+     * <li>`fulfilled`: the billing request has been fulfilled and a payment
      * created</li>
-     * <li>`cancelled`: the billing_request has been cancelled and cannot be
+     * <li>`cancelled`: the billing request has been cancelled and cannot be
      * used</li>
      * </ul>
      */

lib/Resources/BillingRequestFlow.php

@@ -22,6 +22,7 @@
  * @property-read $lock_customer_details
  * @property-read $redirect_uri
  * @property-read $session_token
+ * @property-read $show_redirect_buttons
  */
 class BillingRequestFlow extends BaseResource
 {
@@ -88,8 +89,18 @@ class BillingRequestFlow extends BaseResource
     protected $redirect_uri;
 
     /**
-     * Session token populated when responding to the initalise action
+     * Session token populated when responding to the initialise action
      */
     protected $session_token;
 
+    /**
+     * If true, the payer will be able to see redirect action buttons on Thank
+     * You page. These action buttons will provide a way to connect back to the
+     * billing request flow app if opened within a mobile app. For successful
+     * flow, the button will take the payer back the billing request flow where
+     * they will see the success screen. For failure, button will take the payer
+     * to url being provided against exit_uri field.
+     */
+    protected $show_redirect_buttons;
+
 }

lib/Resources/BillingRequestTemplate.php

@@ -73,15 +73,27 @@ class BillingRequestTemplate extends BaseResource
      * <ul>
      *   <li>`minimum`: only verify if absolutely required, such as when part of
      * scheme rules</li>
-     *   <li>`recommended`: in addition to minimum, use the GoCardless risk
-     * engine to decide an appropriate level of verification</li>
+     *   <li>`recommended`: in addition to `minimum`, use the GoCardless payment
+     * intelligence solution to decide if a payer should be verified</li>
      *   <li>`when_available`: if verification mechanisms are available, use
      * them</li>
      *   <li>`always`: as `when_available`, but fail to create the Billing
      * Request if a mechanism isn't available</li>
      * </ul>
      * 
-     * If not provided, the `recommended` level is chosen.
+     * By default, all Billing Requests use the `recommended` verification
+     * preference. It uses GoCardless payment intelligence solution to determine
+     * if a payer is fraudulent or not. The verification mechanism is based on
+     * the response and the payer may be asked to verify themselves. If the
+     * feature is not available, `recommended` behaves like `minimum`.
+     * 
+     * If you never wish to take advantage of our reduced risk products and
+     * Verified Mandates as they are released in new schemes, please use the
+     * `minimum` verification preference.
+     * 
+     * See [Billing Requests: Creating Verified
+     * Mandates](https://developer.gocardless.com/getting-started/billing-requests/verified-mandates/)
+     * for more information.
      */
     protected $mandate_request_verify;
 
@@ -104,7 +116,8 @@ class BillingRequestTemplate extends BaseResource
 
     /**
      * [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency
-     * code.
+     * code. `GBP` and `EUR` supported; `GBP` with your customers in the UK and
+     * for `EUR` with your customers in Germany only.
      */
     protected $payment_request_currency;
 
@@ -122,8 +135,12 @@ class BillingRequestTemplate extends BaseResource
     protected $payment_request_metadata;
 
     /**
-     * A Direct Debit scheme. Currently "ach", "bacs", "becs", "becs_nz",
-     * "betalingsservice", "pad" and "sepa_core" are supported.
+     * (Optional) A scheme used for Open Banking payments. Currently
+     * `faster_payments` is supported in the UK (GBP) and `sepa_credit_transfer`
+     * and `sepa_instant_credit_transfer` are supported in Germany (EUR). In
+     * Germany, `sepa_credit_transfer` is used as the default. Please be aware
+     * that `sepa_instant_credit_transfer` may incur an additional fee for your
+     * customer.
      */
     protected $payment_request_scheme;
 

lib/Resources/Payment.php

@@ -99,12 +99,12 @@ 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>PAD</strong> - 12 characters<br /> <strong>SEPA</strong> - 140
-     * characters<br /> Note that this reference must be unique (for each
-     * merchant) for the BECS scheme as it is a scheme requirement. <p
-     * class='restricted-notice'><strong>Restricted</strong>: You can only
-     * specify a payment reference for Bacs payments (that is, when collecting
-     * from the UK) if you're on the <a
+     * <strong>PAD</strong> - scheme doesn't offer references<br />
+     * <strong>SEPA</strong> - 140 characters<br /> Note that this reference
+     * must be unique (for each merchant) for the BECS scheme as it is a scheme
+     * requirement. <p class='restricted-notice'><strong>Restricted</strong>:
+     * You can only 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>
      */

lib/Resources/Refund.php

@@ -71,12 +71,12 @@ 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>PAD</strong> - 12 characters<br /> <strong>SEPA</strong> - 140
-     * characters<br /> Note that this reference must be unique (for each
-     * merchant) for the BECS scheme as it is a scheme requirement. <p
-     * class='restricted-notice'><strong>Restricted</strong>: You can only
-     * specify a payment reference for Bacs payments (that is, when collecting
-     * from the UK) if you're on the <a
+     * <strong>PAD</strong> - scheme doesn't offer references<br />
+     * <strong>SEPA</strong> - 140 characters<br /> Note that this reference
+     * must be unique (for each merchant) for the BECS scheme as it is a scheme
+     * requirement. <p class='restricted-notice'><strong>Restricted</strong>:
+     * You can only 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>
      */

lib/Services/BillingRequestFlowsService.php

@@ -29,7 +29,7 @@ class BillingRequestFlowsService extends BaseService
 
 
     /**
-     * Create a billing request flow
+     * Create a Billing Request Flow
      *
      * Example URL: /billing_request_flows
      *
@@ -53,11 +53,11 @@ public function create($params = array())
     }
 
     /**
-     * Initialise a billing request flow
+     * Initialise a Billing Request Flow
      *
      * Example URL: /billing_request_flows/:identity/actions/initialise
      *
-     * @param  string        $identity Unique identifier, beginning with "BRQ".
+     * @param  string        $identity Unique identifier, beginning with "BRF".
      * @param  string[mixed] $params   An associative array for any params
      * @return BillingRequestFlow
      **/

lib/Services/BillingRequestsService.php

@@ -27,6 +27,7 @@
  * @method confirmPayerDetails()
  * @method cancel()
  * @method notify()
+ * @method fallback()
  */
 class BillingRequestsService extends BaseService
 {
@@ -58,7 +59,7 @@ protected function _doList($params = array())
     }
 
     /**
-     * Create a billing_request
+     * Create a Billing Request
      *
      * Example URL: /billing_requests
      *
@@ -93,7 +94,7 @@ public function create($params = array())
     }
 
     /**
-     * Get a single billing request
+     * Get a single Billing Request
      *
      * Example URL: /billing_requests/:identity
      *
@@ -122,7 +123,7 @@ public function get($identity, $params = array())
     }
 
     /**
-     * Collect customer details for the billing request
+     * Collect customer details for a Billing Request
      *
      * Example URL: /billing_requests/:identity/actions/collect_customer_details
      *
@@ -164,7 +165,7 @@ public function collectCustomerDetails($identity, $params = array())
     }
 
     /**
-     * Collect bank account details for the billing request
+     * Collect bank account details for a Billing Request
      *
      * Example URL: /billing_requests/:identity/actions/collect_bank_account
      *
@@ -206,7 +207,7 @@ public function collectBankAccount($identity, $params = array())
     }
 
     /**
-     * Fulfil a billing request
+     * Fulfil a Billing Request
      *
      * Example URL: /billing_requests/:identity/actions/fulfil
      *
@@ -248,7 +249,7 @@ public function fulfil($identity, $params = array())
     }
 
     /**
-     * Confirm the customer and bank_account details
+     * Confirm the customer and bank account details
      *
      * Example URL: /billing_requests/:identity/actions/confirm_payer_details
      *
@@ -290,7 +291,7 @@ public function confirmPayerDetails($identity, $params = array())
     }
 
     /**
-     * Cancel a billing request
+     * Cancel a Billing Request
      *
      * Example URL: /billing_requests/:identity/actions/cancel
      *
@@ -332,7 +333,7 @@ public function cancel($identity, $params = array())
     }
 
     /**
-     * Notify the customer of a billing request
+     * Notify the customer of a Billing Request
      *
      * Example URL: /billing_requests/:identity/actions/notify
      *
@@ -373,6 +374,48 @@ public function notify($identity, $params = array())
         return $this->getResourceForResponse($response);
     }
 
+    /**
+     * Trigger fallback for a Billing Request
+     *
+     * Example URL: /billing_requests/:identity/actions/fallback
+     *
+     * @param  string        $identity Unique identifier, beginning with "BRQ".
+     * @param  string[mixed] $params   An associative array for any params
+     * @return BillingRequest
+     **/
+    public function fallback($identity, $params = array())
+    {
+        $path = Util::subUrl(
+            '/billing_requests/:identity/actions/fallback',
+            array(
+
+                'identity' => $identity
+            )
+        );
+        if(isset($params['params'])) { 
+            $params['body'] = json_encode(array("data" => (object)$params['params']));
+
+            unset($params['params']);
+        }
+
+
+        try {
+            $response = $this->api_client->post($path, $params);
+        } catch(InvalidStateException $e) {
+            if ($e->isIdempotentCreationConflict()) {
+                if ($this->api_client->error_on_idempotency_conflict) {
+                    throw $e;
+                }
+                return $this->get($e->getConflictingResourceId());
+            }
+
+            throw $e;
+        }
+
+
+        return $this->getResourceForResponse($response);
+    }
+
     /**
      * List Billing Requests
      *

lib/Services/InstitutionsService.php

@@ -28,7 +28,7 @@ class InstitutionsService extends BaseService
 
 
     /**
-     * List institutions
+     * List Institutions
      *
      * Example URL: /institutions
      *
@@ -50,7 +50,7 @@ protected function _doList($params = array())
     }
 
     /**
-     * List institutions
+     * List Institutions
      *
      * Example URL: /institutions
      *

tests/Integration/BillingRequestFlowsIntegrationTest.php

@@ -37,6 +37,7 @@ public function testBillingRequestFlowsCreate()
         $this->assertEquals($body->lock_customer_details, $response->lock_customer_details);
         $this->assertEquals($body->redirect_uri, $response->redirect_uri);
         $this->assertEquals($body->session_token, $response->session_token);
+        $this->assertEquals($body->show_redirect_buttons, $response->show_redirect_buttons);
 
 
         $expectedPathRegex = $this->extract_resource_fixture_path_regex($fixture);
@@ -68,6 +69,7 @@ public function testBillingRequestFlowsInitialise()
         $this->assertEquals($body->lock_customer_details, $response->lock_customer_details);
         $this->assertEquals($body->redirect_uri, $response->redirect_uri);
         $this->assertEquals($body->session_token, $response->session_token);
+        $this->assertEquals($body->show_redirect_buttons, $response->show_redirect_buttons);
 
 
         $expectedPathRegex = $this->extract_resource_fixture_path_regex($fixture);