ดาวน์โหลด gocardless pro php - ดาวน์โหลดซอร์สโค้ด gocardless pro php

gocardless pro php

ซอร์สโค้ดอื่น ๆ

v6.0.0

ดาวน์โหลด

ไลบรารีไคลเอนต์ GoCardless Pro PHP

ไคลเอนต์ PHP สำหรับการโต้ตอบกับ GoCardless Pro API

คู่มือ "เริ่มต้นใช้งาน" พร้อมคัดลอกและวางตัวอย่างโค้ด 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 โดยจัดเตรียมโทเค็นการเข้าถึงและสภาพแวดล้อมที่คุณต้องการใช้ เราขอแนะนำอย่างยิ่งให้จัดเก็บโทเค็นการเข้าถึงของคุณเป็นตัวแปรสภาพแวดล้อม แทนที่จะเก็บไว้ในโค้ดของคุณโดยตรง คุณสามารถโหลดตัวแปรสภาพแวดล้อมจากไฟล์ .env ได้อย่างง่ายดายโดยใช้บางอย่างเช่น phpdotenv แม้ว่าจะไม่อยู่ในการควบคุมเวอร์ชันก็ตาม!

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

คุณสามารถสร้าง access_token ได้จากแท็บ "นักพัฒนา" ในแดชบอร์ด GoCardless

สภาพแวดล้อมอาจเป็น GoCardlessProEnvironment::SANDBOX หรือ GoCardlessProEnvironment::LIVE ขึ้นอยู่กับว่าคุณต้องการใช้แซนด์บ็อกซ์หรือ Live API

สำหรับเอกสารฉบับเต็ม โปรดดูเอกสาร API ของเรา

รับคำขอ

คุณสามารถส่งคำขอเพื่อรับรายการทรัพยากรโดยใช้วิธี list

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

หมายเหตุ: README นี้จะใช้ลูกค้าตลอด แต่ทรัพยากรแต่ละรายการใน API มีอยู่ในไลบรารีนี้

หากคุณต้องการส่งตัวเลือกใดๆ อาร์กิวเมนต์สุดท้าย (หรือเท่านั้น ในกรณีที่ไม่มีพารามิเตอร์ URL) ไปยัง list() คืออาร์เรย์ของพารามิเตอร์ 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 มีคีย์ idempotency ไลบรารีจะแทรกสิ่งเหล่านี้ลงในคำขอของคุณโดยอัตโนมัติเมื่อคุณสร้างทรัพยากร เพื่อป้องกันไม่ให้ทำซ้ำหากมีสิ่งผิดปกติเกิดขึ้นกับ API (เช่น ปัญหาด้านเครือข่ายหรือการหมดเวลา)

คุณยังสามารถระบุคีย์ idempotency ของคุณเองได้ เช่น คุณสามารถใช้ ID ของบันทึกในฐานข้อมูลของคุณ เพื่อปกป้องตัวคุณเองไม่เพียงแต่จากปัญหาเครือข่ายหรือ API เท่านั้น แต่ยังรวมถึงข้อผิดพลาดในด้านของคุณซึ่งอาจนำไปสู่การสร้างซ้ำซ้อน:

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

หากไลบรารีพบข้อขัดแย้งของคีย์ idempotency (นั่นคือ คุณพยายามสร้างทรัพยากรด้วยคีย์ idempotency ที่คุณได้ใช้ไปแล้ว) ไลบรารีจะโหลดและส่งคืนทรัพยากรที่มีอยู่แล้วโดยอัตโนมัติ

การจัดการกับความล้มเหลว

เมื่อ API ส่งคืนข้อผิดพลาด ไลบรารีจะส่งคืนคลาสย่อยที่สอดคล้องกันของ ApiException หนึ่งใน:

InvalidApiUsageException
InvalidStateException
ValidationFailedException

ข้อผิดพลาดประเภทเหล่านี้ครอบคลุมอยู่ในเอกสารประกอบ API

หากข้อผิดพลาดเป็นข้อผิดพลาดของเลเยอร์การขนส่ง HTTP (เช่น การหมดเวลาหรือปัญหาภายในโครงสร้างพื้นฐานของ GoCardless) ไลบรารีจะลองส่งคำขออีกครั้งโดยอัตโนมัติสูงสุด 3 ครั้ง โดยมีความล่าช้า 500 มิลลิวินาทีระหว่างความพยายามแต่ละครั้ง ก่อนที่ ApiConnectionException จะเพิ่มขึ้น

หากไลบรารีไม่สามารถแยกวิเคราะห์การตอบสนองจาก 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();

การจัดการ webhooks

GoCardless รองรับ webhooks ช่วยให้คุณรับการแจ้งเตือนแบบเรียลไทม์เมื่อมีสิ่งต่างๆ เกิดขึ้นในบัญชีของคุณ ดังนั้นคุณจึงสามารถดำเนินการตอบสนองอัตโนมัติได้ เช่น:

เมื่อลูกค้ายกเลิกอาณัติกับธนาคาร ให้ระงับการเป็นสมาชิกคลับของตน
เมื่อการชำระเงินล้มเหลวเนื่องจากไม่มีเงินทุน ให้ทำเครื่องหมายใบแจ้งหนี้ว่ายังไม่ได้ชำระเงิน
เมื่อการสมัครใช้งานของลูกค้าทำให้เกิดการชำระเงินใหม่ ให้บันทึกไว้ในรายการ "การชำระเงินที่ผ่านมา"

ไคลเอนต์อนุญาตให้คุณตรวจสอบได้ว่าเว็บฮุคที่คุณได้รับนั้นมาจาก GoCardless จริง ๆ และแยกวิเคราะห์เป็นออบเจ็กต์ GoCardlessProResourcesEvent ซึ่งง่ายต่อการใช้งาน:

 <?php
// 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 ' );
}