Breaking changes to the Payment Gateway API

Changes:

• Payments now have a setState() method.
• The following states have been renamed:
  "received" => "completed",
  "capture_completed" -> "completed",
  "capture_partially_refunded" -> "partially_refunded",
  "capture_refunded" -> "refunded"
• The authorization_expires timestamp has been replaced by the expires timestamp.
• The authorized timestamp is now automatically set by Payment::preSave() when the state changes to "authorized".
• The captured timestamp has been replaced by the completed timestamp, and is also automatically set by Payment::preSave().
• Payment::isTest() and Payment::setTest() have been replaced by Payment::getPaymentGatewayMode() and Payment::setPaymentGatewayMode(), which now also exist on the payment method. This value is automatically set by Payment::preSave().
• Payment gateways now have the time service available via $this->time.
• PaymentGatewayBase now has getRemoteCustomerId() and setRemoteCustomerId() as a better alternative to $owner->commerce_remote_id, which cares about the active mode, handling the test -> live switch properly.

Updating payment gateways:

• Update the gateway constructor to have the $time service, and pass it along to parent::__construct().
• Replace calls to $payment->state with calls to $payment->setState()
• Rename all mentions of the renamed states, as indicated above.
• Replace calls to $payment->setAuthorizationExpiresTime() with $payment->setExpiresTime()
• Remove all calls to setAuthorizedTime(), setCapturedTime(), and setTest()
• Replace REQUEST_TIME with $this->time->getRequestTime()
• Replace $owner->customer_remote_id usage with $this->getRemoteCustomerId() and $this->setRemoteCustomerId().

Example commits for Braintree:
http://cgit.drupalcode.org/commerce_braintree/commit/?id=1a9f373
http://cgit.drupalcode.org/commerce_braintree/commit/?id=8776c1b

Optional ways to reduce boilerplate

PaymentGatewayBase now has a assertPaymentState() helper for checking the payment state.
Old code:

    if ($payment->getState()->value != 'authorization') {
      throw new \InvalidArgumentException('Only payments in the "authorization" state can be captured.');
    }

New code:

  $this->assertPaymentState($payment, ['authorization']);

There's also an assertPaymentMethod() helper for ensuring that the payment method is not empty and not expired.
Old code:

    if (empty($payment_method)) {
      throw new \InvalidArgumentException('The provided payment has no payment method referenced.');
    }
    if (REQUEST_TIME >= $payment_method->getExpiresTime()) {
      throw new HardDeclineException('The provided payment method has expired');
    }

New code:

  $this->assertPaymentMethod($payment_method);

And a assertRefundAmount() helper for ensuring that the refund amount is not larger than the payment amount.
Old code:

    // Validate the requested amount.
    $balance = $payment->getBalance();
    if ($amount->greaterThan($balance)) {
      throw new InvalidRequestException(sprintf("Can't refund more than %s.", $balance->__toString()));
    }

New code:

$this->assertRefundAmount($payment, $amount);