BraintreeTransactionGateway

Braintree TransactionGateway processor Creates and manages transactions.

Defined (1)

The class is defined in the following location(s).

/classes/lib/Braintree/Braintree/TransactionGateway.php  
  1. final class TransactionGateway 
  2. private $_gateway; 
  3. private $_config; 
  4. private $_http; 
  5.  
  6. public function __construct($gateway) 
  7. $this->_gateway = $gateway; 
  8. $this->_config = $gateway->config; 
  9. $this->_config->assertHasAccessTokenOrKeys(); 
  10. $this->_http = new Http($gateway->config); 
  11.  
  12. public function cloneTransaction($transactionId, $attribs) 
  13. Util::verifyKeys(self::cloneSignature(), $attribs); 
  14. return $this->_doCreate('/transactions/' . $transactionId . '/clone', ['transactionClone' => $attribs]); 
  15.  
  16. /** 
  17. * @ignore 
  18. * @access private 
  19. * @param array $attribs 
  20. * @return object 
  21. */ 
  22. private function create($attribs) 
  23. Util::verifyKeys(self::createSignature(), $attribs); 
  24. return $this->_doCreate('/transactions', ['transaction' => $attribs]); 
  25.  
  26. /** 
  27. * @ignore 
  28. * @access private 
  29. * @param array $attribs 
  30. * @return object 
  31. * @throws Exception\ValidationError 
  32. */ 
  33. private function createNoValidate($attribs) 
  34. $result = $this->create($attribs); 
  35. return Util::returnObjectOrThrowException(__CLASS__, $result); 
  36. /** 
  37. * @deprecated since version 2.3.0 
  38. * @access public 
  39. * @param array $attribs 
  40. * @return object 
  41. */ 
  42. public function createFromTransparentRedirect($queryString) 
  43. trigger_error("DEPRECATED: Please use TransparentRedirectRequest::confirm", E_USER_NOTICE); 
  44. $params = TransparentRedirect::parseAndValidateQueryString( 
  45. $queryString 
  46. ); 
  47. return $this->_doCreate( 
  48. '/transactions/all/confirm_transparent_redirect_request',  
  49. ['id' => $params['id']] 
  50. ); 
  51. /** 
  52. * @deprecated since version 2.3.0 
  53. * @access public 
  54. * @param none 
  55. * @return string 
  56. */ 
  57. public function createTransactionUrl() 
  58. trigger_error("DEPRECATED: Please use TransparentRedirectRequest::url", E_USER_NOTICE); 
  59. return $this->_config->baseUrl() . $this->_config->merchantPath() . 
  60. '/transactions/all/create_via_transparent_redirect_request'; 
  61.  
  62. public static function cloneSignature() 
  63. return ['amount', 'channel', ['options' => ['submitForSettlement']]]; 
  64.  
  65. /** 
  66. * creates a full array signature of a valid gateway request 
  67. * @return array gateway request signature format 
  68. */ 
  69. public static function createSignature() 
  70. return [ 
  71. 'amount',  
  72. 'billingAddressId',  
  73. 'channel',  
  74. 'customerId',  
  75. 'deviceData',  
  76. 'deviceSessionId',  
  77. 'fraudMerchantId',  
  78. 'merchantAccountId',  
  79. 'orderId',  
  80. 'paymentMethodNonce',  
  81. 'paymentMethodToken',  
  82. 'purchaseOrderNumber',  
  83. 'recurring',  
  84. 'serviceFeeAmount',  
  85. 'sharedPaymentMethodToken',  
  86. 'sharedCustomerId',  
  87. 'sharedShippingAddressId',  
  88. 'sharedBillingAddressId',  
  89. 'shippingAddressId',  
  90. 'taxAmount',  
  91. 'taxExempt',  
  92. 'threeDSecureToken',  
  93. 'type',  
  94. 'venmoSdkPaymentMethodCode',  
  95. ['creditCard' => 
  96. ['token', 'cardholderName', 'cvv', 'expirationDate', 'expirationMonth', 'expirationYear', 'number'],  
  97. ],  
  98. ['customer' => 
  99. 'id', 'company', 'email', 'fax', 'firstName',  
  100. 'lastName', 'phone', 'website'],  
  101. ],  
  102. ['billing' => 
  103. 'firstName', 'lastName', 'company', 'countryName',  
  104. 'countryCodeAlpha2', 'countryCodeAlpha3', 'countryCodeNumeric',  
  105. 'extendedAddress', 'locality', 'postalCode', 'region',  
  106. 'streetAddress'],  
  107. ],  
  108. ['shipping' => 
  109. 'firstName', 'lastName', 'company', 'countryName',  
  110. 'countryCodeAlpha2', 'countryCodeAlpha3', 'countryCodeNumeric',  
  111. 'extendedAddress', 'locality', 'postalCode', 'region',  
  112. 'streetAddress'],  
  113. ],  
  114. ['options' => 
  115. 'holdInEscrow',  
  116. 'storeInVault',  
  117. 'storeInVaultOnSuccess',  
  118. 'submitForSettlement',  
  119. 'addBillingAddressToPaymentMethod',  
  120. 'venmoSdkSession',  
  121. 'storeShippingAddressInVault',  
  122. 'payeeEmail',  
  123. ['three_d_secure' => 
  124. ['required'] 
  125. ],  
  126. ['paypal' => 
  127. 'payeeEmail',  
  128. 'customField',  
  129. 'description',  
  130. ['supplementaryData' => ['_anyKey_']],  
  131. ],  
  132. ['amexRewards' => 
  133. 'requestId',  
  134. 'points',  
  135. 'currencyAmount',  
  136. 'currencyIsoCode' 
  137. ],  
  138. ],  
  139. ['customFields' => ['_anyKey_']],  
  140. ['descriptor' => ['name', 'phone', 'url']],  
  141. ['paypalAccount' => ['payeeEmail']],  
  142. ['apple_pay_card' => ['number', 'cardholder_name', 'cryptogram', 'expiration_month', 'expiration_year']],  
  143. ['industry' => 
  144. ['industryType',  
  145. ['data' => 
  146. 'folioNumber',  
  147. 'checkInDate',  
  148. 'checkOutDate',  
  149. 'travelPackage',  
  150. 'departureDate',  
  151. 'lodgingCheckInDate',  
  152. 'lodgingCheckOutDate',  
  153. 'lodgingName',  
  154. 'roomRate' 
  155. ]; 
  156.  
  157. public static function submitForSettlementSignature() 
  158. return ['orderId', ['descriptor' => ['name', 'phone', 'url']]]; 
  159.  
  160. /** 
  161. * @access public 
  162. * @param array $attribs 
  163. * @return Result\Successful|Result\Error 
  164. */ 
  165. public function credit($attribs) 
  166. return $this->create(array_merge($attribs, ['type' => Transaction::CREDIT])); 
  167.  
  168. /** 
  169. * @access public 
  170. * @param array $attribs 
  171. * @return Result\Successful|Result\Error 
  172. * @throws Exception\ValidationError 
  173. */ 
  174. public function creditNoValidate($attribs) 
  175. $result = $this->credit($attribs); 
  176. return Util::returnObjectOrThrowException(__CLASS__, $result); 
  177.  
  178. /** 
  179. * @access public 
  180. * @param string id 
  181. * @return Transaction 
  182. */ 
  183. public function find($id) 
  184. $this->_validateId($id); 
  185. try { 
  186. $path = $this->_config->merchantPath() . '/transactions/' . $id; 
  187. $response = $this->_http->get($path); 
  188. return Transaction::factory($response['transaction']); 
  189. } catch (Exception\NotFound $e) { 
  190. throw new Exception\NotFound( 
  191. 'transaction with id ' . $id . ' not found' 
  192. ); 
  193. /** 
  194. * new sale 
  195. * @param array $attribs 
  196. * @return array 
  197. */ 
  198. public function sale($attribs) 
  199. return $this->create(array_merge(['type' => Transaction::SALE], $attribs)); 
  200.  
  201. /** 
  202. * roughly equivalent to the ruby bang method 
  203. * @access public 
  204. * @param array $attribs 
  205. * @return array 
  206. * @throws Exception\ValidationsFailed 
  207. */ 
  208. public function saleNoValidate($attribs) 
  209. $result = $this->sale($attribs); 
  210. return Util::returnObjectOrThrowException(__CLASS__, $result); 
  211.  
  212. /** 
  213. * Returns a ResourceCollection of transactions matching the search query. 
  214. * If <b>query</b> is a string, the search will be a basic search. 
  215. * If <b>query</b> is a hash, the search will be an advanced search. 
  216. * For more detailed information and examples, see {@link http://www.braintreepayments.com/gateway/transaction-api#searching http://www.braintreepaymentsolutions.com/gateway/transaction-api} 
  217. * @param mixed $query search query 
  218. * @param array $options options such as page number 
  219. * @return ResourceCollection 
  220. * @throws InvalidArgumentException 
  221. */ 
  222. public function search($query) 
  223. $criteria = []; 
  224. foreach ($query as $term) { 
  225. $criteria[$term->name] = $term->toparam(); 
  226.  
  227. $path = $this->_config->merchantPath() . '/transactions/advanced_search_ids'; 
  228. $response = $this->_http->post($path, ['search' => $criteria]); 
  229. if (array_key_exists('searchResults', $response)) { 
  230. $pager = [ 
  231. 'object' => $this,  
  232. 'method' => 'fetch',  
  233. 'methodArgs' => [$query] 
  234. ]; 
  235.  
  236. return new ResourceCollection($response, $pager); 
  237. } else { 
  238. throw new Exception\DownForMaintenance(); 
  239.  
  240. public function fetch($query, $ids) 
  241. $criteria = []; 
  242. foreach ($query as $term) { 
  243. $criteria[$term->name] = $term->toparam(); 
  244. $criteria["ids"] = TransactionSearch::ids()->in($ids)->toparam(); 
  245. $path = $this->_config->merchantPath() . '/transactions/advanced_search'; 
  246. $response = $this->_http->post($path, ['search' => $criteria]); 
  247.  
  248. return Util::extractattributeasarray( 
  249. $response['creditCardTransactions'],  
  250. 'transaction' 
  251. ); 
  252.  
  253. /** 
  254. * void a transaction by id 
  255. * @param string $id transaction id 
  256. * @return Result\Successful|Result\Error 
  257. */ 
  258. public function void($transactionId) 
  259. $this->_validateId($transactionId); 
  260.  
  261. $path = $this->_config->merchantPath() . '/transactions/'. $transactionId . '/void'; 
  262. $response = $this->_http->put($path); 
  263. return $this->_verifyGatewayResponse($response); 
  264. /** 
  265. */ 
  266. public function voidNoValidate($transactionId) 
  267. $result = $this->void($transactionId); 
  268. return Util::returnObjectOrThrowException(__CLASS__, $result); 
  269.  
  270. public function submitForSettlement($transactionId, $amount = null, $attribs = []) 
  271. $this->_validateId($transactionId); 
  272. Util::verifyKeys(self::submitForSettlementSignature(), $attribs); 
  273. $attribs['amount'] = $amount; 
  274.  
  275. $path = $this->_config->merchantPath() . '/transactions/'. $transactionId . '/submit_for_settlement'; 
  276. $response = $this->_http->put($path, ['transaction' => $attribs]); 
  277. return $this->_verifyGatewayResponse($response); 
  278.  
  279. public function submitForSettlementNoValidate($transactionId, $amount = null, $attribs = []) 
  280. $result = $this->submitForSettlement($transactionId, $amount, $attribs); 
  281. return Util::returnObjectOrThrowException(__CLASS__, $result); 
  282.  
  283. public function submitForPartialSettlement($transactionId, $amount, $attribs = []) 
  284. $this->_validateId($transactionId); 
  285. Util::verifyKeys(self::submitForSettlementSignature(), $attribs); 
  286. $attribs['amount'] = $amount; 
  287.  
  288. $path = $this->_config->merchantPath() . '/transactions/'. $transactionId . '/submit_for_partial_settlement'; 
  289. $response = $this->_http->post($path, ['transaction' => $attribs]); 
  290. return $this->_verifyGatewayResponse($response); 
  291.  
  292. public function holdInEscrow($transactionId) 
  293. $this->_validateId($transactionId); 
  294.  
  295. $path = $this->_config->merchantPath() . '/transactions/' . $transactionId . '/hold_in_escrow'; 
  296. $response = $this->_http->put($path, []); 
  297. return $this->_verifyGatewayResponse($response); 
  298.  
  299. public function releaseFromEscrow($transactionId) 
  300. $this->_validateId($transactionId); 
  301.  
  302. $path = $this->_config->merchantPath() . '/transactions/' . $transactionId . '/release_from_escrow'; 
  303. $response = $this->_http->put($path, []); 
  304. return $this->_verifyGatewayResponse($response); 
  305.  
  306. public function cancelRelease($transactionId) 
  307. $this->_validateId($transactionId); 
  308.  
  309. $path = $this->_config->merchantPath() . '/transactions/' . $transactionId . '/cancel_release'; 
  310. $response = $this->_http->put($path, []); 
  311. return $this->_verifyGatewayResponse($response); 
  312.  
  313. public function refund($transactionId, $amount = null) 
  314. self::_validateId($transactionId); 
  315.  
  316. $params = ['transaction' => ['amount' => $amount]]; 
  317. $path = $this->_config->merchantPath() . '/transactions/' . $transactionId . '/refund'; 
  318. $response = $this->_http->post($path, $params); 
  319. return $this->_verifyGatewayResponse($response); 
  320.  
  321. /** 
  322. * sends the create request to the gateway 
  323. * @ignore 
  324. * @param var $subPath 
  325. * @param array $params 
  326. * @return mixed 
  327. */ 
  328. public function _doCreate($subPath, $params) 
  329. $fullPath = $this->_config->merchantPath() . $subPath; 
  330. $response = $this->_http->post($fullPath, $params); 
  331.  
  332. return $this->_verifyGatewayResponse($response); 
  333.  
  334. /** 
  335. * verifies that a valid transaction id is being used 
  336. * @ignore 
  337. * @param string transaction id 
  338. * @throws InvalidArgumentException 
  339. */ 
  340. private function _validateId($id = null) { 
  341. if (empty($id)) { 
  342. throw new InvalidArgumentException( 
  343. 'expected transaction id to be set' 
  344. ); 
  345. if (!preg_match('/^[0-9a-z]+$/', $id)) { 
  346. throw new InvalidArgumentException( 
  347. $id . ' is an invalid transaction id.' 
  348. ); 
  349.  
  350. /** 
  351. * generic method for validating incoming gateway responses 
  352. * creates a new Transaction object and encapsulates 
  353. * it inside a Result\Successful object, or 
  354. * encapsulates a Errors object inside a Result\Error 
  355. * alternatively, throws an Unexpected exception if the response is invalid. 
  356. * @ignore 
  357. * @param array $response gateway response values 
  358. * @return Result\Successful|Result\Error 
  359. * @throws Exception\Unexpected 
  360. */ 
  361. private function _verifyGatewayResponse($response) 
  362. if (isset($response['transaction'])) { 
  363. // return a populated instance of Transaction 
  364. return new Result\Successful( 
  365. Transaction::factory($response['transaction']) 
  366. ); 
  367. } else if (isset($response['apiErrorResponse'])) { 
  368. return new Result\Error($response['apiErrorResponse']); 
  369. } else { 
  370. throw new Exception\Unexpected( 
  371. "Expected transaction or apiErrorResponse" 
  372. );