Merge pull request #1026 from stripe/remi/codegen-4bd4c01

Add support for the Payout Reverse API

.travis.yml

@@ -37,7 +37,7 @@ matrix:
 
 env:
   global:
-    - STRIPE_MOCK_VERSION=0.99.0
+    - STRIPE_MOCK_VERSION=0.101.0
 cache:
   directories:
     - $HOME/.composer/cache/files

lib/Invoice.php

@@ -70,7 +70,7 @@
  * @property null|string|\Stripe\Account|\Stripe\AlipayAccount|\Stripe\BankAccount|\Stripe\BitcoinReceiver|\Stripe\Card|\Stripe\Source $default_source ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription's default source, if any, or to the customer's default source.
  * @property null|\Stripe\TaxRate[] $default_tax_rates The tax rates applied to this invoice, if any.
  * @property null|string $description An arbitrary string attached to the object. Often useful for displaying to users. Referenced as 'memo' in the Dashboard.
- * @property null|\Stripe\Discount $discount Describes the current discount applied to this invoice, if there is one.
+ * @property null|\Stripe\Discount $discount Describes the current discount applied to this invoice, if there is one. Not populated if there are multiple discounts.
  * @property null|(string|\Stripe\Discount)[] $discounts The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use <code>expand[]=discounts</code> to expand each discount.
  * @property null|int $due_date The date on which payment for this invoice is due. This value will be <code>null</code> for invoices where <code>collection_method=charge_automatically</code>.
  * @property null|int $ending_balance Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.

lib/Payout.php

@@ -30,6 +30,8 @@
  * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
  * @property null|\Stripe\StripeObject $metadata Set of <a href="https://stripe.com/docs/api/metadata">key-value pairs</a> that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  * @property string $method The method used to send this payout, which can be <code>standard</code> or <code>instant</code>. <code>instant</code> is only supported for payouts to debit cards. (See <a href="https://stripe.com/blog/instant-payouts-for-marketplaces">Instant payouts for marketplaces</a> for more information.)
+ * @property null|string|\Stripe\Payout $original_payout If the payout reverses another, this is the ID of the original payout.
+ * @property null|string|\Stripe\Payout $reversed_by If the payout was reversed, this is the ID of the payout that reverses this payout.
  * @property string $source_type The source balance this payout came from. One of <code>card</code>, <code>fpx</code>, or <code>bank_account</code>.
  * @property null|string $statement_descriptor Extra information about a payout to be displayed on the user's bank statement.
  * @property string $status Current status of the payout: <code>paid</code>, <code>pending</code>, <code>in_transit</code>, <code>canceled</code> or <code>failed</code>. A payout is <code>pending</code> until it is submitted to the bank, when it becomes <code>in_transit</code>. The status then changes to <code>paid</code> if the transaction goes through, or to <code>failed</code> or <code>canceled</code> (within 5 business days). Some failed payouts may initially show as <code>paid</code> but then change to <code>failed</code>.
@@ -86,4 +88,21 @@ public function cancel($params = null, $opts = null)
 
         return $this;
     }
+
+    /**
+     * @param null|array $params
+     * @param null|array|string $opts
+     *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
+     * @return Payout the reversed payout
+     */
+    public function reverse($params = null, $opts = null)
+    {
+        $url = $this->instanceUrl() . '/reverse';
+        list($response, $opts) = $this->_request('post', $url, $params, $opts);
+        $this->refreshFrom($response, $opts);
+
+        return $this;
+    }
 }

lib/Service/CustomerService.php

@@ -24,7 +24,7 @@ public function all($params = null, $opts = null)
 
     /**
      * Returns a list of transactions that updated the customer’s <a
-     * href="/docs/api/customers/object#customer_object-balance"><code>balance</code></a>.
+     * href="/docs/billing/customer/balance">balances</a>.
      *
      * @param string $parentId
      * @param null|array $params
@@ -87,8 +87,8 @@ public function create($params = null, $opts = null)
     }
 
     /**
-     * Creates an immutable transaction that updates the customer’s <a
-     * href="/docs/api/customers/object#customer_object-balance"><code>balance</code></a>.
+     * Creates an immutable transaction that updates the customer’s credit <a
+     * href="/docs/billing/customer/balance">balance</a>.
      *
      * @param string $parentId
      * @param null|array $params
@@ -224,8 +224,8 @@ public function retrieve($id, $params = null, $opts = null)
     }
 
     /**
-     * Retrieves a specific transaction that updated the customer’s <a
-     * href="/docs/api/customers/object#customer_object-balance"><code>balance</code></a>.
+     * Retrieves a specific customer balance transaction that updated the customer’s <a
+     * href="/docs/billing/customer/balance">balances</a>.
      *
      * @param string $parentId
      * @param string $id
@@ -304,7 +304,7 @@ public function update($id, $params = null, $opts = null)
     }
 
     /**
-     * Most customer balance transaction fields are immutable, but you may update its
+     * Most credit balance transaction fields are immutable, but you may update its
      * <code>description</code> and <code>metadata</code>.
      *
      * @param string $parentId

lib/Service/InvoiceService.php

@@ -175,8 +175,8 @@ public function sendInvoice($id, $params = null, $opts = null)
     /**
      * At any time, you can preview the upcoming invoice for a customer. This will show
      * you all the charges that are pending, including subscription renewal charges,
-     * invoice item charges, etc. It will also show you any discount that is applicable
-     * to the customer.
+     * invoice item charges, etc. It will also show you any discounts that are
+     * applicable to the invoice.
      *
      * Note that when you are viewing an upcoming invoice, you are simply viewing a
      * preview – the invoice has not yet been created. As such, the upcoming invoice

lib/Service/PayoutService.php

@@ -84,6 +84,29 @@ public function retrieve($id, $params = null, $opts = null)
         return $this->request('get', $this->buildPath('/v1/payouts/%s', $id), $params, $opts);
     }
 
+    /**
+     * Reverses a payout by debiting the destination bank account. Only payouts for
+     * connected accounts to US bank accounts may be reversed at this time. If the
+     * payout is in the <code>pending</code> status,
+     * <code>/v1/payouts/:id/cancel</code> should be used instead.
+     *
+     * By requesting a reversal via <code>/v1/payouts/:id/reverse</code>, you confirm
+     * that the authorized signatory of the selected bank account has authorized the
+     * debit on the bank account and that no other authorization is required.
+     *
+     * @param string $id
+     * @param null|array $params
+     * @param null|array|\Stripe\Util\RequestOptions $opts
+     *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
+     * @return \Stripe\Payout
+     */
+    public function reverse($id, $params = null, $opts = null)
+    {
+        return $this->request('post', $this->buildPath('/v1/payouts/%s/reverse', $id), $params, $opts);
+    }
+
     /**
      * Updates the specified payout by setting the values of the parameters passed. Any
      * parameters not provided will be left unchanged. This request accepts only the

tests/Stripe/PayoutTest.php

@@ -80,4 +80,15 @@ public function testIsCancelable()
         $resource->cancel();
         static::assertInstanceOf(\Stripe\Payout::class, $resource);
     }
+
+    public function testIsReverseable()
+    {
+        $resource = Payout::retrieve(self::TEST_RESOURCE_ID);
+        $this->expectsRequest(
+            'post',
+            '/v1/payouts/' . $resource->id . '/reverse'
+        );
+        $resource->reverse();
+        static::assertInstanceOf(\Stripe\Payout::class, $resource);
+    }
 }

tests/Stripe/Service/PayoutServiceTest.php

@@ -71,6 +71,16 @@ public function testRetrieve()
         static::assertInstanceOf(\Stripe\Payout::class, $resource);
     }
 
+    public function testReverse()
+    {
+        $this->expectsRequest(
+            'post',
+            '/v1/payouts/' . self::TEST_RESOURCE_ID . '/reverse'
+        );
+        $resource = $this->service->reverse(self::TEST_RESOURCE_ID);
+        static::assertInstanceOf(\Stripe\Payout::class, $resource);
+    }
+
     public function testUpdate()
     {
         $this->expectsRequest(