Idempotency support

See https://docs.mangopay.com/api-references/idempotency-support/

MangoPay/ApiCardPreAuthorizations.php

@@ -11,8 +11,8 @@ class ApiCardPreAuthorizations extends Libraries\ApiBase {
      * @param \MangoPay\CardPreAuthorization $cardPreAuthorization PreAuthorization object to create
      * @return \MangoPay\CardPreAuthorization PreAuthorization object returned from API
      */
-    public function Create($cardPreAuthorization) {
-        return $this->CreateObject('preauthorization_create', $cardPreAuthorization, '\MangoPay\CardPreAuthorization');
+    public function Create($cardPreAuthorization, $idempotencyKey = null) {
+        return $this->CreateObject('preauthorization_create', $cardPreAuthorization, '\MangoPay\CardPreAuthorization', null, null, $idempotencyKey);
     }
 
     /**

MangoPay/ApiCardRegistrations.php

@@ -11,8 +11,8 @@ class ApiCardRegistrations extends Libraries\ApiBase {
      * @param \MangoPay\CardRegistration $cardRegistration Card registration object to create
      * @return \MangoPay\CardRegistration Card registration object returned from API
      */
-    public function Create($cardRegistration) {
-        return $this->CreateObject('cardregistration_create', $cardRegistration, '\MangoPay\CardRegistration');
+    public function Create($cardRegistration, $idempotencyKey = null) {
+        return $this->CreateObject('cardregistration_create', $cardRegistration, '\MangoPay\CardRegistration', null, null, $idempotencyKey);
     }
 
     /**

MangoPay/ApiCards.php

@@ -33,8 +33,8 @@ public function Update($card) {
      * @param \MangoPay\TemporaryPaymentCard $paymentCard Payment card object to create
      * @return \MangoPay\TemporaryPaymentCard Card registration object returned from API
      */
-    public function CreateTemporaryPaymentCard($paymentCard) {
-        return $this->CreateObject('temp_paymentcards_create', $paymentCard, '\MangoPay\TemporaryPaymentCard');
+    public function CreateTemporaryPaymentCard($paymentCard, $idempotencyKey = null) {
+        return $this->CreateObject('temp_paymentcards_create', $paymentCard, '\MangoPay\TemporaryPaymentCard', null, null, $idempotencyKey);
     }
 
     /**

MangoPay/ApiDisputes.php

@@ -129,9 +129,9 @@ public function GetRepudiation($repudiationId)
      * @param Int|GUID $repudiationId Repudiation identifier
      * @return \MangoPay\Transfer Transfer instance returned from API
      */
-    public function CreateSettlementTransfer($settlementTransfer, $repudiationId)
+    public function CreateSettlementTransfer($settlementTransfer, $repudiationId, $idempotencyKey = null)
     {
-        return $this->CreateObject('disputes_repudiation_create_settlement', $settlementTransfer, '\MangoPay\Transfer', $repudiationId);
+        return $this->CreateObject('disputes_repudiation_create_settlement', $settlementTransfer, '\MangoPay\Transfer', $repudiationId, null, $idempotencyKey);
     }
 
     /**
@@ -163,9 +163,9 @@ public function UpdateDisputeDocument($disputeId, $disputeDocument)
      * @param \MangoPay\DisputeDocument $disputeDocument Dispute document to be created
      * @return \MangoPay\DisputeDocument Dispute document returned from API
      */
-    public function CreateDisputeDocument($disputeId, $disputeDocument)
+    public function CreateDisputeDocument($disputeId, $disputeDocument, $idempotencyKey = null)
     {
-        return $this->CreateObject('disputes_document_create', $disputeDocument, '\MangoPay\DisputeDocument', $disputeId);
+        return $this->CreateObject('disputes_document_create', $disputeDocument, '\MangoPay\DisputeDocument', $disputeId, null, $idempotencyKey);
     }
 
     /**
@@ -174,10 +174,10 @@ public function CreateDisputeDocument($disputeId, $disputeDocument)
      * @param Int|GUID $disputeDocumentId Dispute document identifier
      * @param \MangoPay\DisputeDocumentPage $disputeDocumentPage Dispute document page object
      */
-    public function CreateDisputeDocumentPage($disputeId, $disputeDocumentId, $disputeDocumentPage)
+    public function CreateDisputeDocumentPage($disputeId, $disputeDocumentId, $disputeDocumentPage, $idempotencyKey = null)
     {
         try{
-            $this->CreateObject('disputes_document_page_create', $disputeDocumentPage, null, $disputeId, $disputeDocumentId);
+            $this->CreateObject('disputes_document_page_create', $disputeDocumentPage, null, $disputeId, $disputeDocumentId, $idempotencyKey);
         } catch (\MangoPay\Libraries\ResponseException $exc) {
             if ($exc->getCode() != 204) {
                 throw $exc;
@@ -192,7 +192,7 @@ public function CreateDisputeDocumentPage($disputeId, $disputeDocumentId, $dispu
      * @param string $file File path
      * @throws \MangoPay\Libraries\Exception
      */
-    public function CreateDisputeDocumentPageFromFile($disputeId, $disputeDocumentId, $file) {
+    public function CreateDisputeDocumentPageFromFile($disputeId, $disputeDocumentId, $file, $idempotencyKey = null) {
 
         $filePath = $file;
         if (is_array($file)) {
@@ -214,6 +214,6 @@ public function CreateDisputeDocumentPageFromFile($disputeId, $disputeDocumentId
             throw new \MangoPay\Libraries\Exception('Content of the file cannot be empty');
         }
 
-        $this->CreateDisputeDocumentPage($disputeId, $disputeDocumentId, $disputeDocumentPage);
+        $this->CreateDisputeDocumentPage($disputeId, $disputeDocumentId, $disputeDocumentPage, $idempotencyKey);
     }
 }

MangoPay/ApiHooks.php

@@ -11,8 +11,8 @@ class ApiHooks extends Libraries\ApiBase {
      * @param Hook $hook
      * @return \MangoPay\Hook Hook object returned from API
      */
-    public function Create($hook) {
-        return $this->CreateObject('hooks_create', $hook, '\MangoPay\Hook');
+    public function Create($hook, $idempotencyKey = null) {
+        return $this->CreateObject('hooks_create', $hook, '\MangoPay\Hook', null, null, $idempotencyKey);
     }
 
     /**

MangoPay/ApiPayIns.php

@@ -11,10 +11,10 @@ class ApiPayIns extends Libraries\ApiBase {
      * @param \MangoPay\PayIn $payIn \MangoPay\PayIn object
      * @return \MangoPay\PayIn Object returned from API
      */
-    public function Create($payIn) {
+    public function Create($payIn, $idempotencyKey = null) {
         $paymentKey = $this->GetPaymentKey($payIn);
         $executionKey = $this->GetExecutionKey($payIn);
-        return $this->CreateObject('payins_' . $paymentKey . '-' . $executionKey . '_create', $payIn, '\MangoPay\PayIn');
+        return $this->CreateObject('payins_' . $paymentKey . '-' . $executionKey . '_create', $payIn, '\MangoPay\PayIn', null, null, $idempotencyKey);
     }
 
     /**
@@ -32,8 +32,8 @@ public function Get($payInId) {
      * @param \MangoPay\Refund $refund Refund object to create
      * @return \MangoPay\Refund Object returned by REST API
      */
-    public function CreateRefund($payInId, $refund) {
-        return $this->CreateObject('payins_createrefunds', $refund, '\MangoPay\Refund', $payInId);
+    public function CreateRefund($payInId, $refund, $idempotencyKey = null) {
+        return $this->CreateObject('payins_createrefunds', $refund, '\MangoPay\Refund', $payInId, null, $idempotencyKey);
     }
 
     /**
@@ -45,8 +45,8 @@ public function CreateRefund($payInId, $refund) {
      * @param \MangoPay\TemporaryImmediatePayIn $immediatePayIn Immediate pay-in object to create
      * @return \MangoPay\TemporaryImmediatePayIn Immediate pay-in object returned from API
      */
-    public function CreateTemporaryImmediatePayIn($immediatePayIn) {
-        return $this->CreateObject('temp_immediatepayins_create', $immediatePayIn, '\MangoPay\TemporaryImmediatePayIn');
+    public function CreateTemporaryImmediatePayIn($immediatePayIn, $idempotencyKey = null) {
+        return $this->CreateObject('temp_immediatepayins_create', $immediatePayIn, '\MangoPay\TemporaryImmediatePayIn', null, null, $idempotencyKey);
     }
 
     private function GetPaymentKey($payIn) {

MangoPay/ApiPayOuts.php

@@ -11,9 +11,9 @@ class ApiPayOuts extends Libraries\ApiBase {
      * @param PayOut $payOut
      * @return \MangoPay\PayOut Object returned from API
      */
-    public function Create($payOut) {
+    public function Create($payOut, $idempotencyKey = null) {
         $paymentKey = $this->GetPaymentKey($payOut);
-        return $this->CreateObject('payouts_' . $paymentKey . '_create', $payOut, '\MangoPay\PayOut');
+        return $this->CreateObject('payouts_' . $paymentKey . '_create', $payOut, '\MangoPay\PayOut', null, null, $idempotencyKey);
     }
 
     /**

MangoPay/ApiResponses.php

@@ -0,0 +1,23 @@
+<?php
+namespace MangoPay;
+
+/**
+ * Class to management MangoPay API for responses
+ * See 
+ */
+
+ /**
+ * Class ApiResponses
+ * @package MangoPay
+ */
+class ApiResponses extends Libraries\ApiBase {
+
+    /**
+     * Get response from previous call by idempotency key
+     * @param object $idempotencyKey Idempotency key
+	 * @return \MangoPay\Response Entity of Response object
+     */
+    public function Get($idempotencyKey) {
+        return $this->GetObject('responses_get', $idempotencyKey, 'MangoPay\Response');
+    }
+}

MangoPay/ApiTransfers.php

@@ -11,8 +11,8 @@ class ApiTransfers extends Libraries\ApiBase {
      * @param \MangoPay\Transfer $transfer
      * @return \MangoPay\Transfer Transfer object returned from API
      */
-    public function Create($transfer) {
-        return $this->CreateObject('transfers_create', $transfer, '\MangoPay\Transfer');
+    public function Create($transfer, $idempotencyKey = null) {
+        return $this->CreateObject('transfers_create', $transfer, '\MangoPay\Transfer', null, null, $idempotencyKey);
     }
 
     /**
@@ -30,7 +30,7 @@ public function Get($transfer) {
      * @param \MangoPay\Refund $refund Refund object to create
      * @return \MangoPay\Refund Object returned by REST API
      */
-    public function CreateRefund($transferId, $refund) {
-        return $this->CreateObject('transfers_createrefunds', $refund, '\MangoPay\Refund', $transferId);
+    public function CreateRefund($transferId, $refund, $idempotencyKey = null) {
+        return $this->CreateObject('transfers_createrefunds', $refund, '\MangoPay\Refund', $transferId, null, $idempotencyKey);
     }
 }

MangoPay/ApiUsers.php

@@ -16,7 +16,7 @@ class ApiUsers extends Libraries\ApiBase {
      * @return UserLegal/UserNatural User object returned from API
      * @throws Libraries\Exception If occur Wrong entity class for user
      */
-    public function Create($user) {
+    public function Create($user, $idempotencyKey = null) {
 
         $className = get_class($user);
         if ($className == 'MangoPay\UserNatural')
@@ -26,7 +26,7 @@ public function Create($user) {
         else
             throw new Libraries\Exception('Wrong entity class for user');
 
-        $response = $this->CreateObject($methodKey, $user);
+        $response = $this->CreateObject($methodKey, $user, null, null, null, $idempotencyKey);
         return $this->GetUserResponse($response);
     }
 
@@ -107,9 +107,9 @@ public function Update($user) {
      * @param \MangoPay\BankAccount $bankAccount Entity of bank account object
      * @return \MangoPay\BankAccount Create bank account object
      */
-    public function CreateBankAccount($userId, $bankAccount) {
+    public function CreateBankAccount($userId, $bankAccount, $idempotencyKey = null) {
         $type = $this->GetBankAccountType($bankAccount);
-        return $this->CreateObject('users_createbankaccounts_' . $type, $bankAccount, '\MangoPay\BankAccount', $userId);
+        return $this->CreateObject('users_createbankaccounts_' . $type, $bankAccount, '\MangoPay\BankAccount', $userId, null, $idempotencyKey);
     }
 
     /**
@@ -178,8 +178,8 @@ public function GetCards($userId, & $pagination = null, $sorting = null) {
      * @param \MangoPay\KycDocument $kycDocument
      * @return \MangoPay\KycDocument Document returned from API
      */
-    public function CreateKycDocument($userId, $kycDocument) {
-        return $this->CreateObject('kyc_documents_create', $kycDocument, '\MangoPay\KycDocument', $userId);
+    public function CreateKycDocument($userId, $kycDocument, $idempotencyKey = null) {
+        return $this->CreateObject('kyc_documents_create', $kycDocument, '\MangoPay\KycDocument', $userId, null, $idempotencyKey);
     }
 
     /**
@@ -222,10 +222,10 @@ public function UpdateKycDocument($userId, $kycDocument) {
      * @param \MangoPay\KycPage $kycPage KYC Page
      * @throws \MangoPay\Libraries\Exception
      */
-    public function CreateKycPage($userId, $kycDocumentId, $kycPage) {
+    public function CreateKycPage($userId, $kycDocumentId, $kycPage, $idempotencyKey = null) {
 
         try{
-            $this->CreateObject('kyc_page_create', $kycPage, null, $userId, $kycDocumentId);
+            $this->CreateObject('kyc_page_create', $kycPage, null, $userId, $kycDocumentId, $idempotencyKey);
         } catch (\MangoPay\Libraries\ResponseException $exc) {
             if ($exc->getCode() != 204)
                 throw $exc;
@@ -239,7 +239,7 @@ public function CreateKycPage($userId, $kycDocumentId, $kycPage) {
      * @param string $file File path
      * @throws \MangoPay\Libraries\Exception
      */
-    public function CreateKycPageFromFile($userId, $kycDocumentId, $file) {
+    public function CreateKycPageFromFile($userId, $kycDocumentId, $file, $idempotencyKey = null) {
 
         $filePath = $file;
         if (is_array($file)) {
@@ -258,7 +258,7 @@ public function CreateKycPageFromFile($userId, $kycDocumentId, $file) {
         if (empty($kycPage->File))
             throw new \MangoPay\Libraries\Exception('Content of the file cannot be empty');
 
-        $this->CreateKycPage($userId, $kycDocumentId, $kycPage);
+        $this->CreateKycPage($userId, $kycDocumentId, $kycPage, $idempotencyKey);
     }
 
     /**

MangoPay/ApiWallets.php

@@ -11,8 +11,8 @@ class ApiWallets extends Libraries\ApiBase {
      * @param Wallet $wallet
      * @return \MangoPay\Wallet Wallet object returned from API
      */
-    public function Create($wallet) {
-        return $this->CreateObject('wallets_create', $wallet, '\MangoPay\Wallet');
+    public function Create($wallet, $idempotencyKey = null) {
+        return $this->CreateObject('wallets_create', $wallet, '\MangoPay\Wallet', null, null, $idempotencyKey);
     }
 
     /**

MangoPay/Libraries/ApiBase.php

@@ -20,6 +20,8 @@ abstract class ApiBase {
         'authentication_base' => array( '/api/clients/', RequestType::POST ),
         'authentication_oauth' => array( '/oauth/token ', RequestType::POST ),
 
+        'responses_get' => array( '/responses/%s', RequestType::GET),
+
         'events_all' => array( '/events', RequestType::GET ),
 
         'hooks_create' => array( '/hooks', RequestType::POST ),
@@ -116,7 +118,7 @@ abstract class ApiBase {
         // Please, contact with support before using these features or if you have any questions.
         'temp_paymentcards_create' => array( '/temp/paymentcards', RequestType::POST ),
         'temp_paymentcards_get' => array( '/temp/paymentcards/%s', RequestType::GET ),
-        'temp_immediatepayins_create' => array( '/temp/immediate-payins', RequestType::POST )
+        'temp_immediatepayins_create' => array( '/temp/immediate-payins', RequestType::POST ),
     );
 
     /**
@@ -153,7 +155,7 @@ protected function GetRequestType($key){
      * @param int $entityId Entity identifier
      * @return object Response data
      */
-    protected function CreateObject($methodKey, $entity, $responseClassName = null, $entityId = null, $subEntityId = null) {
+    protected function CreateObject($methodKey, $entity, $responseClassName = null, $entityId = null, $subEntityId = null, $idempotencyKey = null) {
 
         if (is_null($entityId))
             $urlMethod = $this->GetRequestUrl($methodKey);
@@ -167,7 +169,7 @@ protected function CreateObject($methodKey, $entity, $responseClassName = null,
             $requestData = $this->BuildRequestData($entity);
 
         $rest = new RestTool(true, $this->_root);
-        $response = $rest->Request($urlMethod, $this->GetRequestType($methodKey), $requestData);
+        $response = $rest->Request($urlMethod, $this->GetRequestType($methodKey), $requestData, $idempotencyKey);
 
         if (!is_null($responseClassName))
             return $this->CastResponseToEntity($response, $responseClassName);
@@ -225,7 +227,7 @@ protected function GetList($methodKey, & $pagination, $responseClassName = null,
             $additionalUrlParams["sort"] = $sorting->GetSortParameter();
         }
 
-        $response = $rest->Request($urlMethod, $this->GetRequestType($methodKey), null, $pagination, $additionalUrlParams);
+        $response = $rest->Request($urlMethod, $this->GetRequestType($methodKey), null, null, $pagination, $additionalUrlParams);
 
         if (!is_null($responseClassName))
             return $this->CastResponseToEntity($response, $responseClassName);

MangoPay/Libraries/RestTool.php

@@ -85,7 +85,7 @@ public function AddRequestHttpHeader($httpHeader) {
      * @param array Array with additional parameters to URL. Expected keys: "sort" and "filter"
      * @return object Response data
      */
-    public function Request($urlMethod, $requestType, $requestData = null, & $pagination = null, $additionalUrlParams = null) {
+    public function Request($urlMethod, $requestType, $requestData = null, $idempotencyKey = null, & $pagination = null, $additionalUrlParams = null) {
 
         $this->_requestType = $requestType;
         $this->_requestData = $requestData;
@@ -94,7 +94,7 @@ public function Request($urlMethod, $requestType, $requestData = null, & $pagina
         if ($this->_root->Config->DebugMode)
             $logClass::Debug('++++++++++++++++++++++ New request ++++++++++++++++++++++', '');
 
-        $this->BuildRequest($urlMethod, $pagination, $additionalUrlParams);
+        $this->BuildRequest($urlMethod, $pagination, $additionalUrlParams, $idempotencyKey);
         $responseResult = $this->RunRequest();
 
         if(!is_null($pagination)){
@@ -138,7 +138,7 @@ private function RunRequest() {
      * @param String $urlMethod Type of method in REST API
      * @throws Exception If some parameters are not set
      */
-    private function BuildRequest($urlMethod, $pagination, $additionalUrlParams = null) {
+    private function BuildRequest($urlMethod, $pagination, $additionalUrlParams = null, $idempotencyKey = null) {
 
         $urlTool = new UrlTool($this->_root);
         $restUrl = $urlTool->GetRestUrl($urlMethod, $this->_authRequired, $pagination, $additionalUrlParams);
@@ -184,6 +184,7 @@ private function BuildRequest($urlMethod, $pagination, $additionalUrlParams = nu
             $logClass::Debug('RequestType', $this->_requestType);
 
         $httpHeaders = $this->GetHttpHeaders();
+		if ($idempotencyKey != null) array_push($httpHeaders, 'Idempotency-Key: ' . $idempotencyKey);
         curl_setopt($this->_curlHandle, CURLOPT_HTTPHEADER, $httpHeaders);
         if ($this->_root->Config->DebugMode) 
             $logClass::Debug('HTTP Headers', $httpHeaders);
@@ -249,8 +250,9 @@ private function ReadResponseHeader($handle, $header) {
      */
     private function GetHttpHeaders(){
         // return if already created...
-        if (!is_null($this->_requestHttpHeaders))
+        if (!is_null($this->_requestHttpHeaders)) {
             return $this->_requestHttpHeaders;
+		}
 
         // ...or initialize with default headers
         $this->_requestHttpHeaders = array();

MangoPay/MangoPayApi.php

@@ -33,6 +33,12 @@ class MangoPayApi {
      * @var ApiOAuth
      */
     public $AuthenticationManager;
+
+    /**
+     * Provides responses methods
+     * @var ApiResponses 
+     */
+    public $Responses;
 
     /**
      * Clients methods
@@ -135,6 +141,7 @@ function __construct() {
 
         // API managers
         $this->AuthenticationManager = new Libraries\ApiOAuth($this);
+        $this->Responses = new ApiResponses($this);
         $this->Clients = new Libraries\ApiClients($this);
         $this->Users = new ApiUsers($this);
         $this->Wallets = new ApiWallets($this);