Viewing file:  RestCreateSubscriptionRequest.php (14.37 KB) -rw-r--r--
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
<?php
/**
* PayPal REST Create Subscription Request
*/
namespace Omnipay\PayPal\Message;
/**
* PayPal REST Create Subscription Request
*
* Use this call to create a billing agreement for the buyer. The response
* for this call includes these HATEOAS links: an approval_url link and an
* execute link. Each returned link includes the token for the agreement.
*
* For PayPal payments:
*
* * After successfully creating the agreement, direct the user to the
* approval_url on the PayPal site so that the user can approve the agreement.
* * Call the execute link to execute the billing agreement.
*
* Note: Billing agreements for credit card payments execute automatically
* when created. There is no need for the user to approve the agreement or
* to execute the agreement.
*
* ### Request Data
*
* Pass the agreement details in the body of a POST call, including the
* following agreement object properties:
*
* * name (string). Required.
* * description (string). Required.
* * start_date (string). Format yyyy-MM-dd z, as defined in ISO8601. Required.
* * agreement_details (array)
* * payer (array). Required
* * shipping_address (array). Should be provided if it is different to the
* default address.
* * override_merchant_preferences (array).
* * override_charge_models (array).
* * plan (array). Required.
*
* ### Example
*
* <code>
* // Create a gateway for the PayPal REST Gateway
* // (routes to GatewayFactory::create)
* $gateway = Omnipay::create('PayPal_Rest');
*
* // Initialise the gateway
* $gateway->initialize(array(
* 'clientId' => 'MyPayPalClientId',
* 'secret' => 'MyPayPalSecret',
* 'testMode' => true, // Or false when you are ready for live transactions
* ));
*
* // Do a create plan transaction on the gateway
* $transaction = $gateway->createPlan(array(
* 'name' => 'Test Plan',
* 'description' => 'A plan created for testing',
* 'type' => $gateway::BILLING_PLAN_TYPE_FIXED,
* 'paymentDefinitions' => [
* [
* 'name' => 'Monthly Payments for 12 months',
* 'type' => $gateway::PAYMENT_TRIAL,
* 'frequency' => $gateway::BILLING_PLAN_FREQUENCY_MONTH,
* 'frequency_interval' => 1,
* 'cycles' => 12,
* 'amount' => ['value' => 10.00, 'currency' => 'USD'],
* ],
* ],
* ));
* $response = $transaction->send();
* if ($response->isSuccessful()) {
* echo "Create Plan transaction was successful!\n";
* $plan_id = $response->getTransactionReference();
* echo "Plan reference = " . $plan_id . "\n";
* }
*
* // Do a create subscription transaction on the gateway
* $transaction = $gateway->createSubscription(array(
* 'name' => 'Test Subscription',
* 'description' => 'A subscription created for testing',
* 'startDate' => new \DateTime(), // now
* 'planId' => $plan_id,
* 'payerDetails => ['payment_method' => 'paypal'],
* ));
* $response = $transaction->send();
* if ($response->isSuccessful()) {
* echo "Create Subscription transaction was successful!\n";
* if ($response->isRedirect()) {
* echo "Response is a redirect\n";
* echo "Redirect URL = " . $response->getRedirectUrl();
* $subscription_id = $response->getTransactionReference();
* echo "Subscription reference = " . $subscription_id;
* }
* }
* </code>
*
* ### Request Sample
*
* This is from the PayPal web site:
*
* <code>
* curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements \
* -H 'Content-Type:application/json' \
* -H 'Authorization: Bearer <Access-Token>' \
* -d '{
* "name": "T-Shirt of the Month Club Agreement",
* "description": "Agreement for T-Shirt of the Month Club Plan",
* "start_date": "2015-02-19T00:37:04Z",
* "plan": {
* "id": "P-94458432VR012762KRWBZEUA"
* },
* "payer": {
* "payment_method": "paypal"
* },
* "shipping_address": {
* "line1": "111 First Street",
* "city": "Saratoga",
* "state": "CA",
* "postal_code": "95070",
* "country_code": "US"
* }
* }'
* }'
* </code>
*
* ### Response Sample
*
* This is from the PayPal web site:
*
* <code>
* {
* "name": "T-Shirt of the Month Club Agreement",
* "description": "Agreement for T-Shirt of the Month Club Plan",
* "plan": {
* "id": "P-94458432VR012762KRWBZEUA",
* "state": "ACTIVE",
* "name": "T-Shirt of the Month Club Plan",
* "description": "Template creation.",
* "type": "FIXED",
* "payment_definitions": [
* {
* "id": "PD-50606817NF8063316RWBZEUA",
* "name": "Regular Payments",
* "type": "REGULAR",
* "frequency": "Month",
* "amount": {
* "currency": "USD",
* "value": "100"
* },
* "charge_models": [
* {
* "id": "CHM-92S85978TN737850VRWBZEUA",
* "type": "TAX",
* "amount": {
* "currency": "USD",
* "value": "12"
* }
* },
* {
* "id": "CHM-55M5618301871492MRWBZEUA",
* "type": "SHIPPING",
* "amount": {
* "currency": "USD",
* "value": "10"
* }
* }
* ],
* "cycles": "12",
* "frequency_interval": "2"
* }
* ],
* "merchant_preferences": {
* "setup_fee": {
* "currency": "USD",
* "value": "1"
* },
* "max_fail_attempts": "0",
* "return_url": "http://www.return.com",
* "cancel_url": "http://www.cancel.com",
* "auto_bill_amount": "YES",
* "initial_fail_amount_action": "CONTINUE"
* }
* },
* "links": [
* {
* "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-0JP008296V451950C",
* "rel": "approval_url",
* "method": "REDIRECT"
* },
* {
* "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-0JP008296V451950C/agreement-execute",
* "rel": "execute",
* "method": "POST"
* }
* ],
* "start_date": "2015-02-19T00:37:04Z"
* }
* </code>
*
* ### Known Issues
*
* PayPal subscription payments cannot be refunded. PayPal is working on this functionality
* for their future API release. In order to refund a PayPal subscription payment, you will
* need to use the PayPal web interface to refund it manually.
*
* @link https://developer.paypal.com/docs/api/#create-an-agreement
* @see RestCreatePlanRequest
* @see Omnipay\PayPal\RestGateway
*/
class RestCreateSubscriptionRequest extends AbstractRestRequest
{
/**
* Get the agreement name
*
* @return string
*/
public function getName()
{
return $this->getParameter('name');
}
/**
* Set the agreement name
*
* @param string $value
* @return RestCreateSubscriptionRequest provides a fluent interface.
*/
public function setName($value)
{
return $this->setParameter('name', $value);
}
/**
* Get the plan ID
*
* @return string
*/
public function getPlanId()
{
return $this->getParameter('planId');
}
/**
* Set the plan ID
*
* @param string $value
* @return RestCreateSubscriptionRequest provides a fluent interface.
*/
public function setPlanId($value)
{
return $this->setParameter('planId', $value);
}
/**
* Get the agreement start date
*
* @return \DateTime
*/
public function getStartDate()
{
return $this->getParameter('startDate');
}
/**
* Set the agreement start date
*
* @param \DateTime $value
* @return RestCreateSubscriptionRequest provides a fluent interface.
*/
public function setStartDate(\DateTime $value)
{
return $this->setParameter('startDate', $value);
}
/**
* Get the agreement details
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @return array
* @link https://developer.paypal.com/docs/api/#agreementdetails-object
*/
public function getAgreementDetails()
{
return $this->getParameter('agreementDetails');
}
/**
* Set the agreement details
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @param array $value
* @return RestCreateSubscriptionRequest provides a fluent interface.
* @link https://developer.paypal.com/docs/api/#agreementdetails-object
*/
public function setAgreementDetails(array $value)
{
return $this->setParameter('agreementDetails', $value);
}
/**
* Get the payer details
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @return array
* @link https://developer.paypal.com/docs/api/#payer-object
*/
public function getPayerDetails()
{
return $this->getParameter('payerDetails');
}
/**
* Set the payer details
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @param array $value
* @return RestCreateSubscriptionRequest provides a fluent interface.
* @link https://developer.paypal.com/docs/api/#payer-object
*/
public function setPayerDetails(array $value)
{
return $this->setParameter('payerDetails', $value);
}
/**
* Get the shipping address
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @return array
* @link https://developer.paypal.com/docs/api/#address-object
*/
public function getShippingAddress()
{
return $this->getParameter('shippingAddress');
}
/**
* Set the shipping address
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @param array $value
* @return RestCreateSubscriptionRequest provides a fluent interface.
* @link https://developer.paypal.com/docs/api/#address-object
*/
public function setShippingAddress(array $value)
{
return $this->setParameter('shippingAddress', $value);
}
/**
* Get preferences to override the plan merchant preferences
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @return array
* @link https://developer.paypal.com/docs/api/#merchantpreferences-object
*/
public function getMerchantPreferences()
{
return $this->getParameter('merchantPreferences');
}
/**
* Set preferences to override the plan merchant preferences
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @param array $value
* @return RestCreateSubscriptionRequest provides a fluent interface.
* @link https://developer.paypal.com/docs/api/#merchantpreferences-object
*/
public function setMerchantPreferences(array $value)
{
return $this->setParameter('merchantPreferences', $value);
}
/**
* Get charge model to override the plan charge model
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @return array
* @link https://developer.paypal.com/docs/api/#overridechargemodel-object
*/
public function getChargeModel()
{
return $this->getParameter('chargeModel');
}
/**
* Set preferences to override the plan merchant preferences
*
* See the class documentation and the PayPal REST API documentation for
* a description of the array elements.
*
* @param array $value
* @return RestCreateSubscriptionRequest provides a fluent interface.
* @link https://developer.paypal.com/docs/api/#merchantpreferences-object
*/
public function setChargeModel(array $value)
{
return $this->setParameter('chargeModel', $value);
}
public function getData()
{
$this->validate('name', 'description', 'startDate', 'payerDetails', 'planId');
$data = array(
'name' => $this->getName(),
'description' => $this->getDescription(),
'start_date' => $this->getStartDate()->format('c'),
'agreement_details' => $this->getAgreementDetails(),
'payer' => $this->getPayerDetails(),
'plan' => array(
'id' => $this->getPlanId(),
),
'shipping_address' => $this->getShippingAddress(),
'override_merchant_preferences' => $this->getMerchantPreferences(),
'override_charge_models' => $this->getChargeModel(),
);
return $data;
}
/**
* Get transaction endpoint.
*
* Subscriptions are created using the /billing-agreements resource.
*
* @return string
*/
protected function getEndpoint()
{
return parent::getEndpoint() . '/payments/billing-agreements';
}
protected function createResponse($data, $statusCode)
{
return $this->response = new RestAuthorizeResponse($this, $data, $statusCode);
}
}
|