gocardless pro php
v6.0.0
Un cliente PHP para interactuar con la API de GoCardless Pro.
La forma recomendada de instalar gocardless-pro es utilizando Composer.
# Install Composer
curl -sS https://getcomposer.org/installer | php A continuación, ejecute el comando Composer para instalar la última versión estable de gocardless-pro .
php composer.phar require gocardless/gocardless-proDespués de la instalación, necesitarás el cargador automático de Composer:
require ' vendor/autoload.php ' ; Cree una instancia GoCardlessProClient , proporcionando su token de acceso y el entorno que desea utilizar. Le recomendamos encarecidamente que almacene su token de acceso como una variable de entorno, en lugar de hacerlo directamente en su código. Puedes cargar fácilmente las variables de entorno desde un archivo .env usando algo como phpdotenv, ¡aunque mantenlo fuera del control de versiones!
$ access_token = getenv ( ' GC_ACCESS_TOKEN ' );
$ client = new GoCardlessPro Client ([
' access_token ' => $ access_token ,
' environment ' => GoCardlessPro Environment :: SANDBOX
]); Puedes crear un access_token desde la pestaña "Desarrolladores" en tu panel de GoCardless.
El entorno puede ser GoCardlessProEnvironment::SANDBOX o GoCardlessProEnvironment::LIVE , dependiendo de si desea utilizar el entorno de pruebas o la API en vivo.
Para obtener la documentación completa, consulte nuestros documentos API.
Puede realizar una solicitud para obtener una lista de recursos utilizando el método list .
$ client -> customers ()-> list ();Nota: Este README utilizará clientes en todo momento, pero cada uno de los recursos de la API está disponible en esta biblioteca.
Si necesita pasar alguna opción, el último (o único, en ausencia de parámetros de URL) argumento de list() es una matriz de parámetros de URL:
$ customers = $ client -> customers ()-> list ([ ' params ' => [ ' limit ' => 400 ]]); Una llamada a list() devuelve una instancia de ListResponse . Puede utilizar su atributo records para recorrer los resultados.
echo count ( $ customers -> records );
foreach ( $ customers -> records as $ resource ) {
echo $ resource -> given_name ;
}En el caso de que se necesite un parámetro de URL, la firma del método contendrá los argumentos requeridos:
$ customer = $ client -> customers ()-> get ( $ customer_id );
echo $ customer -> given_name ;Al igual que con la lista, el último argumento puede ser una matriz de opciones, con cualquier parámetro de URL proporcionado:
$ client -> customers ()-> get ( $ customer_id , [ ' params ' => [ ' some_flag ' => true ]]); Tanto las instancias de recursos individuales como las de ListResponse tienen un atributo api_response , que le permite acceder a las siguientes propiedades de la solicitud:
statusheadersbody $ api_response = $ client -> customers ()-> get ( $ customer_id )-> api_response ;
echo $ api_response -> status_code ;Para solicitudes POST y PUT, debe proporcionar un cuerpo para su solicitud pasándolo como primer argumento.
$ client -> customers ()-> create ([
' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
]);Al igual que con las solicitudes GET, si se requiere algún parámetro, estos son lo primero:
$ client -> customers ()-> update ( $ customer_id , [
' params ' => [ ' family_name ' => ' Smith ' ]
]);La API de GoCardless incluye claves de idempotencia. La biblioteca los insertará automáticamente en su solicitud cuando cree un recurso, evitando que se duplique si algo sale mal con la API (por ejemplo, problemas de red o un tiempo de espera).
También puede especificar su propia clave de idempotencia; podría, por ejemplo, usar ID de registros en su base de datos, protegiéndose no solo de problemas de red o API, sino también de errores por su parte que podrían llevar a una doble creación:
$ client -> customers ()-> create ([
' params ' => [ ' given_name ' => ' Pete ' , ' family_name ' => ' Hamilton ' ]
' headers ' => [ ' Idempotency-Key ' => ' ABC123 ' ]
]);Si la biblioteca encuentra un conflicto de clave de idempotencia (es decir, intenta crear un recurso con una clave de idempotencia que ya ha utilizado), cargará y devolverá automáticamente el recurso ya existente.
Cuando la API devuelve un error, la biblioteca devolverá una subclase correspondiente de ApiException , una de las siguientes:
InvalidApiUsageExceptionInvalidStateExceptionValidationFailedExceptionEstos tipos de errores se tratan en la documentación de la API.
Si el error es un error de la capa de transporte HTTP (por ejemplo, tiempos de espera o problemas dentro de la infraestructura de GoCardless), la biblioteca reintentará automáticamente las solicitudes hasta 3 veces, con un retraso de 500 ms entre intentos, antes de que se genere una ApiConnectionException .
Si la biblioteca no puede analizar la respuesta de GoCardless, generará una 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.
}Se puede acceder a las propiedades de la excepción con los siguientes métodos:
$e->getType();$e->getCode();$e->getErrors();$e->getDocumentationUrl();$e->getMessage();$e->getRequestId();$e->getApiResponse();GoCardless admite webhooks, lo que le permite recibir notificaciones en tiempo real cuando suceden cosas en su cuenta, para que pueda tomar acciones automáticas en respuesta, por ejemplo:
El cliente le permite validar que un webhook que recibe proviene genuinamente de GoCardless y analizarlo en objetos GoCardlessProResourcesEvent con los que es fácil trabajar:
// 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 ' );
}Para obtener más detalles sobre cómo trabajar con webhooks, consulte nuestra guía "Introducción".
Esta biblioteca cliente solo admite PHP >= 8.1. Las versiones anteriores de PHP ahora se consideran al final de su vida útil y pueden estar expuestas a vulnerabilidades de seguridad.
Este cliente se genera automáticamente a partir de Crank, una cadena de herramientas que esperamos abrir pronto. Por ahora, los problemas deberían informarse en este repositorio.
¡No modifique el código fuente usted mismo, sus cambios serán anulados!
