gocardless pro php 下載 - gocardless pro php 原始碼下載

gocardless pro php

其他源碼

v6.0.0

下載

GoCardless Pro PHP 用戶端程式庫

用於與 GoCardless Pro API 互動的 PHP 用戶端。

包含複製和貼上 PHP 程式碼範例的「入門」指南
API參考
作曲家包
變更日誌

安裝

安裝gocardless-pro建議方法是使用 Composer。

 # Install Composer
curl -sS https://getcomposer.org/installer | php

接下來，執行 Composer 指令來安裝最新穩定版本的gocardless-pro 。

php composer.phar require gocardless/gocardless-pro

安裝後，你需要需要Composer的自動載入器：

 require ' vendor/autoload.php ' ;

初始化客戶端

建立一個GoCardlessProClient實例，提供您的存取權杖和您要使用的環境。我們強烈建議將您的存取權杖儲存為環境變量，而不是直接儲存在程式碼中。您可以使用 phpdotenv 之類的工具輕鬆從.env檔案載入環境變量，但不要將其置於版本控制之外！

 $ access_token = getenv ( ' GC_ACCESS_TOKEN ' );
$ client = new  GoCardlessPro  Client ([
  ' access_token ' => $ access_token ,
  ' environment '  =>  GoCardlessPro  Environment :: SANDBOX
]);

您可以從 GoCardless 儀表板的「開發人員」標籤建立access_token 。

環境可以是GoCardlessProEnvironment::SANDBOX或GoCardlessProEnvironment::LIVE ，這取決於您要使用沙箱還是即時 API。

如需完整文檔，請參閱我們的 API 文件。

獲取請求

您可以使用list方法發出獲取資源清單的請求。

 $ client -> customers ()-> list ();

注意：本自述文件將始終使用客戶，但 API 中的每個資源都可以在該庫中使用。

如果需要傳遞任何選項， list()的最後一個（或唯一的，在沒有 URL 參數的情況下）參數是一個 URL 參數陣列：

 $ customers = $ client -> customers ()-> list ([ ' params ' => [ ' limit ' => 400 ]]);

對list()呼叫傳回ListResponse的實例。您可以使用其records屬性來迭代結果。

 echo count ( $ customers -> records );
foreach ( $ customers -> records as $ resource ) {
  echo $ resource -> given_name ;
}

如果需要 URL 參數，方法簽章將包含所需的參數：

 $ customer = $ client -> customers ()-> get ( $ customer_id );
echo $ customer -> given_name ;

與清單一樣，最後一個參數可以是一個選項數組，其中包含給定的任何 URL 參數：

 $ client -> customers ()-> get ( $ customer_id , [ ' params ' => [ ' some_flag ' => true ]]);

單一資源和 ListResponse 實例都有一個api_response屬性，它允許您存取請求的下列屬性：

status
headers
body

 $ api_response = $ client -> customers ()-> get ( $ customer_id )-> api_response ;
echo $ api_response -> status_code ;

POST/PUT 請求

對於 POST 和 PUT 請求，您需要透過將其作為第一個參數傳遞來提供請求正文。

 $ client -> customers ()-> create ([
  ' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
]);

與 GET 請求一樣，如果需要任何參數，這些參數首先出現：

 $ client -> customers ()-> update ( $ customer_id , [
  ' params ' => [ ' family_name ' => ' Smith ' ]
]);

GoCardless API 包含冪等金鑰。當您建立資源時，該程式庫會自動將這些注入到您的請求中，從而防止在 API 出現問題（例如網路問題或逾時）時出現重複。

您還可以指定自己的冪等性金鑰 - 例如，您可以使用資料庫中記錄的 ID，不僅可以保護自己免受網路或 API 問題的影響，還可以避免可能導致重複建立的錯誤：

 $ client -> customers ()-> create ([
  ' params ' =>  [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
  ' headers ' => [ ' Idempotency-Key ' => ' ABC123 ' ]
]);

如果函式庫遇到冪等鍵衝突（即，您嘗試使用已使用的冪等鍵建立資源），它將自動載入並傳回已存在的資源。

處理故障

當 API 傳回錯誤時，程式庫將傳回ApiException的對應子類，其中之一：

InvalidApiUsageException
InvalidStateException
ValidationFailedException

API 文件中介紹了這些類型的錯誤。

如果錯誤是 HTTP 傳輸層錯誤（例如逾時或 GoCardless 基礎架構內的問題），則在引發ApiConnectionException之前，程式庫將自動重試請求最多 3 次，兩次嘗試之間有 500 毫秒的延遲。

如果函式庫無法解析來自 GoCardless 的回應，它將拋出MalformedResponseException 。

 try {
  $ client -> customer ()-> create ([
    ' params ' => [ ' invalid_name ' => ' Pete ' ]
  ]);
} catch (  GoCardlessPro  Core  Exception  ApiException $ e ) {
  // Api request failed / record couldn't be created.
} catch (  GoCardlessPro  Core  Exception  MalformedResponseException $ e ) {
  // Unexpected non-JSON response.
} catch (  GoCardlessPro  Core  Exception  ApiConnectionException $ e ) {
  // Network error.
}

可以使用以下方法存取異常的屬性：

$e->getType();
$e->getCode();
$e->getErrors();
$e->getDocumentationUrl();
$e->getMessage();
$e->getRequestId();
$e->getApiResponse();

處理網路鉤子

GoCardless 支援 webhook，讓您在帳戶發生事件時收到即時通知，以便您可以採取自動操作進行回應，例如：

當客戶取消銀行授權時，暫停其俱樂部會員資格
當由於缺乏資金而付款失敗時，將其發票標記為未付
當客戶的訂閱產生新的付款時，將其記錄在他們的「過去的付款」清單中

用戶端可讓您驗證收到的 Webhook 是否真正來自 GoCardless，並將其解析為易於使用的GoCardlessProResourcesEvent物件：

 
// When you create a webhook endpoint, you can specify a secret. When GoCardless sends
// you a webhook, it will sign the body using that secret. Since only you and GoCardless
// know the secret, you can check the signature and ensure that the webhook is truly
// from GoCardless.
//
// We recommend storing your webhook endpoint secret in an environment variable
// for security, but you could include it as a string directly in your code
$ webhook_endpoint_secret = getenv ( ' GOCARDLESS_WEBHOOK_ENDPOINT_SECRET ' );

$ request_body = file_get_contents ( ' php://input ' );

$ headers = getallheaders ();
$ signature_header = $ headers [ ' Webhook-Signature ' ];

try {
     $ events = GoCardlessPro  Webhook :: parse ( $ request_body , $ signature_header , $ webhook_endpoint_secret );

     foreach ( $ events as $ event ) {
         // You can access each event in the webhook.
         echo $ event -> id ;
     }

     header ( ' HTTP/1.1 200 OK ' );
} catch ( GoCardlessPro  Core  Exception  InvalidSignatureException ) {
     // The webhook doesn't appear to be genuinely from GoCardless, as the signature
     // included in the `Webhook-Signature` header doesn't match the one computed with
     // your webhook endpoint secret and the body.
     header ( ' HTTP/1.1 498 Invalid Token ' );
}