diff --git a/lib/PayPal/Api/PayoutItem.php b/lib/PayPal/Api/PayoutItem.php index 4a97dd5..96723b8 100644 --- a/lib/PayPal/Api/PayoutItem.php +++ b/lib/PayPal/Api/PayoutItem.php @@ -162,4 +162,29 @@ class PayoutItem extends PayPalResourceModel return $ret; } + /** + * Cancels the unclaimed payment using the items id passed in the request URI. If an unclaimed item is not claimed within 30 days, the funds will be automatically returned to the sender. This call can be used to cancel the unclaimed item prior to the automatic 30-day return. + * + * @param string $payoutItemId + * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials. + * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls + * @return PayoutItemDetails + */ + public static function cancel($payoutItemId, $apiContext = null, $restCall = null) + { + ArgumentValidator::validate($payoutItemId, 'payoutItemId'); + $payLoad = ""; + $json = self::executeCall( + "/v1/payments/payouts-item/$payoutItemId/cancel", + "POST", + $payLoad, + null, + $apiContext, + $restCall + ); + $ret = new PayoutItemDetails(); + $ret->fromJson($json); + return $ret; + } + } diff --git a/sample/doc/assets/behavior.js b/sample/doc/assets/behavior.js index eff03d5..117f5f4 100644 --- a/sample/doc/assets/behavior.js +++ b/sample/doc/assets/behavior.js @@ -192,18 +192,7 @@ f.event={add:function(a,c,d,e,g){var h,i,j,k,l,m,n,o,p,q,r,s;if(!(a.nodeType===3 "pageTitle": "billing/SearchBillingTransactions", "title": "SearchBillingTransactions" }, - "depth": 2, - "outline": [ - { - "type": "heading", - "data": { - "level": 1, - "title": "Search Billing Transactions Sample", - "slug": "search-billing-transactions-sample" - }, - "depth": 1 - } - ] + "depth": 2 }, { "type": "file", "data": { @@ -1183,6 +1172,24 @@ f.event={add:function(a,c,d,e,g){var h,i,j,k,l,m,n,o,p,q,r,s;if(!(a.nodeType===3 "depth": 1, "children": [ { + "type": "file", + "data": { + "language": { + "nameMatchers": [{}, ".fbp"], + "pygmentsLexer": "php", + "singleLineComment": ["//"], + "ignorePrefix": "}", + "foldPrefix": "^", + "name": "PHP" + }, + "sourcePath": "/Users/japatel/Documents/workspace/paypal/PayPal-PHP-SDK/sample/payouts/CancelPayoutItem.php", + "projectPath": "payouts/CancelPayoutItem.php", + "targetPath": "payouts/CancelPayoutItem", + "pageTitle": "payouts/CancelPayoutItem", + "title": "CancelPayoutItem" + }, + "depth": 2 + }, { "type": "file", "data": { "language": { @@ -1199,72 +1206,7 @@ f.event={add:function(a,c,d,e,g){var h,i,j,k,l,m,n,o,p,q,r,s;if(!(a.nodeType===3 "pageTitle": "payouts/CreateBatchPayout", "title": "CreateBatchPayout" }, - "depth": 2, - "outline": [ - { - "type": "heading", - "data": { - "level": 1, - "title": "Create Bulk Payout Sample", - "slug": "create-bulk-payout-sample" - }, - "depth": 1, - "children": [ - { - "type": "heading", - "data": { - "level": 3, - "title": "NOTE:", - "slug": "note" - }, - "depth": 3, - "children": [ - { - "type": "heading", - "data": { - "level": 4, - "title": "Batch Header Instance", - "slug": "batch-header-instance" - }, - "depth": 4 - }, { - "type": "heading", - "data": { - "level": 4, - "title": "Sender Item", - "slug": "sender-item" - }, - "depth": 4 - }, { - "type": "heading", - "data": { - "level": 4, - "title": "Sender Item 2", - "slug": "sender-item-2" - }, - "depth": 4 - }, { - "type": "heading", - "data": { - "level": 4, - "title": "Sender Item 3", - "slug": "sender-item-3" - }, - "depth": 4 - } - ] - }, { - "type": "heading", - "data": { - "level": 3, - "title": "Create Payout", - "slug": "create-payout" - }, - "depth": 3 - } - ] - } - ] + "depth": 2 }, { "type": "file", "data": { @@ -1282,56 +1224,7 @@ f.event={add:function(a,c,d,e,g){var h,i,j,k,l,m,n,o,p,q,r,s;if(!(a.nodeType===3 "pageTitle": "payouts/CreateSinglePayout", "title": "CreateSinglePayout" }, - "depth": 2, - "outline": [ - { - "type": "heading", - "data": { - "level": 1, - "title": "Create Single Synchronous Payout Sample", - "slug": "create-single-synchronous-payout-sample" - }, - "depth": 1, - "children": [ - { - "type": "heading", - "data": { - "level": 3, - "title": "NOTE:", - "slug": "note" - }, - "depth": 3, - "children": [ - { - "type": "heading", - "data": { - "level": 4, - "title": "Batch Header Instance", - "slug": "batch-header-instance" - }, - "depth": 4 - }, { - "type": "heading", - "data": { - "level": 4, - "title": "Sender Item", - "slug": "sender-item" - }, - "depth": 4 - } - ] - }, { - "type": "heading", - "data": { - "level": 3, - "title": "Create Payout", - "slug": "create-payout" - }, - "depth": 3 - } - ] - } - ] + "depth": 2 }, { "type": "file", "data": { @@ -1367,7 +1260,40 @@ f.event={add:function(a,c,d,e,g){var h,i,j,k,l,m,n,o,p,q,r,s;if(!(a.nodeType===3 "pageTitle": "payouts/GetPayoutItemStatus", "title": "GetPayoutItemStatus" }, - "depth": 2 + "depth": 2, + "outline": [ + { + "type": "heading", + "data": { + "level": 1, + "title": "Get Payout Item Status Sample", + "slug": "get-payout-item-status-sample" + }, + "depth": 1, + "children": [ + { + "type": "heading", + "data": { + "level": 2, + "title": "Payout Item ID", + "slug": "payout-item-id" + }, + "depth": 2, + "children": [ + { + "type": "heading", + "data": { + "level": 3, + "title": "Get Payout Item Status", + "slug": "get-payout-item-status" + }, + "depth": 3 + } + ] + } + ] + } + ] } ] }, { diff --git a/sample/doc/payouts/CancelPayoutItem.html b/sample/doc/payouts/CancelPayoutItem.html new file mode 100644 index 0000000..a91545f --- /dev/null +++ b/sample/doc/payouts/CancelPayoutItem.html @@ -0,0 +1,21 @@ +payouts/CancelPayoutItem
payouts/CancelPayoutItem.php
<?php

Cancel Payout Item Status Sample

+

Use this call to cancel an existing, unclaimed transaction. If an unclaimed item is not claimed within 30 days, the funds will be automatically returned to the sender. This call can be used to cancel the unclaimed item prior to the automatic 30-day return. +https://developer.paypal.com/docs/api/#cancel-an-unclaimed-payout-item +API used: POST /v1/payments/payouts-item//cancel

/** @var \PayPal\Api\PayoutBatch $payoutBatch */ +$payoutBatch = require 'CreateSinglePayout.php';

Payout Item ID

+

You can replace this with your Payout Batch Id on already created Payout.

$payoutItems = $payoutBatch->getItems(); +$payoutItem = $payoutItems[0]; +$payoutItemId = $payoutItem->getPayoutItemId(); + +$output = null;

Cancel Payout Item

+

Check if Payout Item is UNCLAIMED, and if so, cancel it.

try { + if ($payoutItem->getTransactionStatus() == 'UNCLAIMED') {

Cancel the Payout Item

$output = \PayPal\Api\PayoutItem::cancel($payoutItemId, $apiContext); + ResultPrinter::printResult("Cancel Unclaimed Payout Item", "PayoutItem", $output->getPayoutItemId(), null, $output); + } else {

The item transaction status is not unclaimed. You can only cancel an unclaimed transaction.

ResultPrinter::printError("Cancel Unclaimed Payout Item", "PayoutItem", null, $payoutItemId, new Exception("Payout Item Status is not UNCLAIMED")); + } +} catch (Exception $ex) { + ResultPrinter::printError("Cancel Unclaimed Payout Item", "PayoutItem", null, $payoutItemId, $ex); + exit(1); +} + +return $output;
\ No newline at end of file diff --git a/sample/doc/payouts/GetPayoutItemStatus.html b/sample/doc/payouts/GetPayoutItemStatus.html index 3ae0f0a..9c3ff3d 100644 --- a/sample/doc/payouts/GetPayoutItemStatus.html +++ b/sample/doc/payouts/GetPayoutItemStatus.html @@ -3,7 +3,8 @@ https://developer.paypal.com/docs/api/#get-the-status-of-a-payout-item API used: GET /v1/payments/payouts-item/

/** @var \PayPal\Api\PayoutBatch $payoutBatch */ $payoutBatch = require 'GetPayoutBatchStatus.php';

Payout Item ID

-

You can replace this with your Payout Batch Id on already created Payout.

$payoutItem = $payoutBatch->getItems()[0]; +

You can replace this with your Payout Batch Id on already created Payout.

$payoutItems = $payoutBatch->getItems(); +$payoutItem = $payoutItems[0]; $payoutItemId = $payoutItem->getPayoutItemId();

Get Payout Item Status

try { $output = \PayPal\Api\PayoutItem::get($payoutItemId, $apiContext); } catch (Exception $ex) { diff --git a/sample/index.php b/sample/index.php index 54484fd..02a896f 100644 --- a/sample/index.php +++ b/sample/index.php @@ -396,6 +396,17 @@ if (PHP_SAPI == 'cli') {
+
  • +
    +
    Cancel Uncliamed Payout Item
    +
    + Try It + Source +
    +
    +
    • diff --git a/sample/payouts/CancelPayoutItem.php b/sample/payouts/CancelPayoutItem.php new file mode 100644 index 0000000..9b0392d --- /dev/null +++ b/sample/payouts/CancelPayoutItem.php @@ -0,0 +1,34 @@ +/cancel + +/** @var \PayPal\Api\PayoutBatch $payoutBatch */ +$payoutBatch = require 'CreateSinglePayout.php'; +// ## Payout Item ID +// You can replace this with your Payout Batch Id on already created Payout. +$payoutItems = $payoutBatch->getItems(); +$payoutItem = $payoutItems[0]; +$payoutItemId = $payoutItem->getPayoutItemId(); + +$output = null; +// ### Cancel Payout Item +// Check if Payout Item is UNCLAIMED, and if so, cancel it. +try { + if ($payoutItem->getTransactionStatus() == 'UNCLAIMED') { + // Cancel the Payout Item + $output = \PayPal\Api\PayoutItem::cancel($payoutItemId, $apiContext); + ResultPrinter::printResult("Cancel Unclaimed Payout Item", "PayoutItem", $output->getPayoutItemId(), null, $output); + } else { + // The item transaction status is not unclaimed. You can only cancel an unclaimed transaction. + ResultPrinter::printError("Cancel Unclaimed Payout Item", "PayoutItem", null, $payoutItemId, new Exception("Payout Item Status is not UNCLAIMED")); + } +} catch (Exception $ex) { + ResultPrinter::printError("Cancel Unclaimed Payout Item", "PayoutItem", null, $payoutItemId, $ex); + exit(1); +} + +return $output; diff --git a/sample/payouts/GetPayoutItemStatus.php b/sample/payouts/GetPayoutItemStatus.php index bdd3414..c13473f 100644 --- a/sample/payouts/GetPayoutItemStatus.php +++ b/sample/payouts/GetPayoutItemStatus.php @@ -10,7 +10,8 @@ $payoutBatch = require 'GetPayoutBatchStatus.php'; // ## Payout Item ID // You can replace this with your Payout Batch Id on already created Payout. -$payoutItem = $payoutBatch->getItems()[0]; +$payoutItems = $payoutBatch->getItems(); +$payoutItem = $payoutItems[0]; $payoutItemId = $payoutItem->getPayoutItemId(); // ### Get Payout Item Status diff --git a/tests/PayPal/Test/Api/PayoutItemTest.php b/tests/PayPal/Test/Api/PayoutItemTest.php index b479c64..1a5a217 100644 --- a/tests/PayPal/Test/Api/PayoutItemTest.php +++ b/tests/PayPal/Test/Api/PayoutItemTest.php @@ -85,6 +85,26 @@ class PayoutItemTest extends \PHPUnit_Framework_TestCase $this->assertNotNull($result); } + /** + * @dataProvider mockProvider + * @param PayoutItem $obj + */ + public function testCancel($obj, $mockApiContext) + { + $mockPPRestCall = $this->getMockBuilder('\PayPal\Transport\PayPalRestCall') + ->disableOriginalConstructor() + ->getMock(); + + $mockPPRestCall->expects($this->any()) + ->method('execute') + ->will($this->returnValue( + PayoutItemDetailsTest::getJson() + )); + + $result = $obj->cancel("payoutItemId", $mockApiContext, $mockPPRestCall); + $this->assertNotNull($result); + } + public function mockProvider() { $obj = self::getObject(); diff --git a/tests/PayPal/Test/Functional/Api/PayoutsFunctionalTest.php b/tests/PayPal/Test/Functional/Api/PayoutsFunctionalTest.php index f4ed062..a594f20 100644 --- a/tests/PayPal/Test/Functional/Api/PayoutsFunctionalTest.php +++ b/tests/PayPal/Test/Functional/Api/PayoutsFunctionalTest.php @@ -65,6 +65,11 @@ class PayoutsFunctionalTest extends \PHPUnit_Framework_TestCase $result = $obj->create($params, null, $this->mockPayPalRestCall); $this->assertNotNull($result); $this->assertEquals(PayoutsFunctionalTest::$batchId, $result->getBatchHeader()->getSenderBatchHeader()->getSenderBatchId()); + $this->assertEquals('SUCCESS', $result->getBatchHeader()->getBatchStatus()); + $items = $result->getItems(); + $this->assertTrue(sizeof($items) > 0); + $item = $items[0]; + $this->assertEquals('UNCLAIMED', $item->getTransactionStatus()); return $result; } @@ -99,4 +104,26 @@ class PayoutsFunctionalTest extends \PHPUnit_Framework_TestCase $this->assertEquals($item->getPayoutItemFee(), $result->getPayoutItemFee()); } + /** + * @depends testCreate + * @param $payoutBatch PayoutBatch + * @return PayoutBatch + */ + public function testCancel($payoutBatch) + { + $items = $payoutBatch->getItems(); + $item = $items[0]; + if ($item->getTransactionStatus() != 'UNCLAIMED') { + $this->markTestSkipped('Transaction status needs to be Unclaimed for this test '); + return; + } + $result = PayoutItem::cancel($item->getPayoutItemId(), null, $this->mockPayPalRestCall); + $this->assertNotNull($result); + $this->assertEquals($item->getPayoutItemId(), $result->getPayoutItemId()); + $this->assertEquals($item->getPayoutBatchId(), $result->getPayoutBatchId()); + $this->assertEquals($item->getTransactionId(), $result->getTransactionId()); + $this->assertEquals($item->getPayoutItemFee(), $result->getPayoutItemFee()); + $this->assertEquals('RETURNED', $result->getTransactionStatus()); + } + } diff --git a/tests/PayPal/Test/Functional/resources/PayoutsFunctionalTest/testCancel.json b/tests/PayPal/Test/Functional/resources/PayoutsFunctionalTest/testCancel.json new file mode 100644 index 0000000..a3850ae --- /dev/null +++ b/tests/PayPal/Test/Functional/resources/PayoutsFunctionalTest/testCancel.json @@ -0,0 +1,76 @@ +{ + "description":"User initiates cancel on unlcaimed payouts item.", + "title":"Cancel item sample", + "runnable":true, + "operationId":"payouts.item.cancel", + "user":{ + "scopes":[ + + ] + }, + "credentials":{ + "oauth":{ + "path":"/v1/oauth/token", + "clientId":"", + "clientSecret":"" + } + }, + "request":{ + "path":"v1/payments/payouts-item/452345/cancel", + "method":"POST", + "headers":{ + "Content-Type":"application/json", + "Content-Encoding":"gzip" + }, + "body":{ + + } + }, + "response":{ + "status":"200 OK", + "headers":{ + "Content-Type":"application/json", + "Content-Encoding":"gzip" + }, + "body":{ + "payout_item_id":"VHBFGN95AWV82", + "transaction_id":"0728664497487461D", + "transaction_status":"RETURNED", + "payout_item_fee":{ + "currency":"USD", + "value":"0.02" + }, + "payout_batch_id":"CDZEC5MJ8R5HY", + "sender_batch_id":"2014021801", + "payout_item":{ + "recipient_type":"EMAIL", + "amount":{ + "value":"1.00", + "currency":"USD" + }, + "note":"Thanks for your patronage!", + "receiver":"anybody01@gmail.com", + "payouts_item_id":"1421342", + "sender_item_id":"14Feb_234" + }, + "time_processed":"2014-01-27T10:17:41Z", + "errors":{ + "name":"RECEIVER_UNREGISTERED", + "message":"Receiver is unregistered", + "information_link": "https://developer.paypal.com/webapps/developer/docs/api/#RECEIVER_UNREGISTERED" + }, + "links":[ + { + "rel":"self", + "href":"https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342", + "method":"GET" + }, + { + "rel":"batch", + "href":"https://api.sandbox.paypal.com/v1/payments/payouts/20140724", + "method":"GET" + } + ] + } + } +} diff --git a/tests/PayPal/Test/Functional/resources/PayoutsFunctionalTest/testCreate.json b/tests/PayPal/Test/Functional/resources/PayoutsFunctionalTest/testCreate.json index 0640d3f..c2c5307 100755 --- a/tests/PayPal/Test/Functional/resources/PayoutsFunctionalTest/testCreate.json +++ b/tests/PayPal/Test/Functional/resources/PayoutsFunctionalTest/testCreate.json @@ -68,7 +68,7 @@ { "payout_item_id": "VHBFGN95AWV82", "transaction_id": "0728664497487461D", - "transaction_status": "SUCCESS", + "transaction_status": "UNCLAIMED", "payout_item_fee": { "currency": "USD", "value": "0.02"