Server : Apache System : Linux server2.corals.io 4.18.0-348.2.1.el8_5.x86_64 #1 SMP Mon Nov 15 09:17:08 EST 2021 x86_64 User : corals ( 1002) PHP Version : 7.4.33 Disable Function : exec,passthru,shell_exec,system Directory : /home/corals/job-board.corals.io/vendor/openpay/sdk/ |
-----------------------------------------------------------------------------
Openpay API v1 Client for PHP (version 1.2.0)
-----------------------------------------------------------------------------
El objetivo de este proyecto es proporcionar un framework reutilizable para
interacturar con el API de Openpay desde cualquier proyecto PHP.
-----------------------------------------------------------------------------
Autor: Openpay SAPI de C.V. ([email protected])
http://www.openpay.mx/
-----------------------------------------------------------------------------
-- REQUERIMIENTOS --
PHP 5.2 o posterior
Extension de PHP cURL
Extension de PHP JSON
Extension de PHP Multibyte String
-- INSTALACION --
Para poder utilizar la librería cliente de Openpay para PHP será necesario:
1. Descomprimir el archivo Openpay.v1.zip dentro de un directorio del
proyecto PHP en el cual se utilizará,
2. Incluir dentro de la(s) página(s) que hará(n) uso del cliente:
require(dirname(__FILE__) . '/Openpay.php');
NOTA: En el ejemplo anterior, la librería está dentro del mismo directorio
del script que se está ejecutando, en caso de que éste no sea el caso se
deberá hacer los ajustes pertinentes en la ruta de la librería.
-- IMPLEMENTACION --
Configuración
Antes de utilizar la librería será necesario configurar el ID de comercio
(Merchant ID) y la llave privada que corresponda (API Key). Hay varias
opciones:
1. Utilizar los métodos Openpay::setId() y Openpay::setApiKey(). Para
utilizar este método solamente hay que pasar el dato correspondiente
a ambos métodos:
Openpay::setId('moiep6umtcnanql3jrxp');
Openpay::setApiKey('sk_3433941e467c4875b178ce26348b0fac');
2. Pasar ambos datos como parámetros al método Openpay::getInstance().
Este método es muy similar al anterior, solamente que ambos parámetros se
pasan simultáneamente al generador de la instancia. El orden de los
métodos es Merchant ID y API Key, respectivamente
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp',
'sk_3433941e467c4875b178ce26348b0fac');
3. Configurar ambos datos como variables de ambiente. Este método permite la
configuración de ambos datos pero a nivel de ambiente, lo cual tiene sus
ventajas ya que no están expuestos directamente en un archivo (para mayor
referencia leer la documentación de PHP). Esta opción no requiere de
ninguna configuración a nivel script.
Modo Sandbox
Cuando se está realizando la implementacion es posible que se desee hacer
pruebas antes de que se hagan cobros normales a una tarjeta de crédito, para
ello es posible utilizar el método OpenPay::setSandboxMode() el cual nos
ayudará a activar o desactivar el modo de prueba en las peticiones que se hagan
a OpenPay.
Openpay::setSandboxMode(FLAG);
Si es necesario, se puede utilizar el método Openpay::getSandboxMode() para
determinar, en cualquier momento, cual es el estatus del modo sandbox:
Openpay::getSandboxMode(); // TRUE/FALSE, dependiendo si el modo está
// activado o no.
Generalidades librería PHP
Una vez configurado el cliente, para realizar operaciones con la librería será
necesario obtener una instancia de la misma, esto se hace con el método
Openpay::getInstance()
$openpay = Openpay::getInstance();
$openpay se tratará entonces, de la instancia del merchant desde la que se
podrán llamar todos los recursos disponibles en la API de Openpay:
1. customers
2. cards
3. charges
4. payouts
5. fees
6. plans
Todos los recursos se acceden como variables públicas, de tal manera, que si
se desea agregar un nuevo cliente se podrá hacer de la siguiente manera:
$openpay->customers->add(PARAMETROS);
Hay que notar que las operaciones de todos y cada uno de los recursos,
devolverán una instancia de dicho recurso, lo que en el ejemplo anterior querrá
decir que la llamada a la operación add() en el recurso Customer devolverá una
instancia del mismo recurso Customer, y así sucesivamente. La única excepción a
este caso es cuando se obtiene un listado de recursos, en cuyo caso el dato
devuelvo será un arreglo de recursos:
$customer = $openpay->customers->add(PARAMETROS);
// devuelve UNA SOLA instancia del recurso Charge
$charge = $customer->charges->create(PARAMETROS);
$customer = $openpay->customers->add(PARAMETROS);
// devuelve UN ARREGLO de instancias del recurso Charge
$chargeList = $customer->charges->getList(PARAMETROS);
Los recursos derivados de Customer son:
1. cards
2. bankaccounts
3. charges
4. transfers
5. payouts
6. suscriptions
Todos los parámetros deben ser arreglos asociativos de la forma:
'NOMBRE_PARAMETRO' => VALOR
Para mayor referencias respecto a los parámetros, datos obligatorios y valores
ceptados, consultar la documentación del API Openpay.
Manejo de errores
El API de Openpay genera distintos tipos de errores de acuerdo al problema que
se haya detectado, por eso, a fin de que el manejo de los errores generados por
la librería sea mejor y más administrable y eficiente, la librería PHP ha
implementado excepciones para las diferentes situaciones:
1. OpenpayApiTransactionError. Esta categoría engloba todas aquellas
situaciones en las que una transacción no se haya completado exitosamente,
por ejemplo: tarjeta declinada, tarjeta con fondos insuficientes, cuenta
destino desactivada, etc.
2. OpenpayApiRequestError. Se refiere a los errores generados cuando se hace
una petición al API. Ejemplos: formateo incorrecto en laos datos de la
petición, valores incorrectos en los parámetros de la petición, errores
internos en el servidor Openpay, etc.
3. OpenpayApiConnectionError. Este tipo de errores son generados cuando la
librería intenta contectarse al API, por ejemplo: timeouts, errores de
servidores de dominio, etc.
4. OpenpayApiAuthError. Se trata de errores de autenticación generados al
momento de contarse al servidor Openpay, o bien, configuración incorrecta
de las credenciales de autenticación (Merchant ID y Api Key).
5. OpenpayApiError. Errores genéricos cuando se procesa una petición. Esta es
la categoría de errores más general.
Todos los errores ponen disponibles el acceso a la información del error que
regrese el API:
1. getDescription(): descripción del error generado por Openpay.
2. getErrorCode(): código de error generado por Openpay. Cuando hay errores de
3. petición o antes de generarla, este valor es igual a cero.
4. getCategory(): categoría de error generada por Openpay. Cuando hay errores
de petición o antes de generarla, este valor es igual a cadena vacía.
5. getHttpCode(): código del error HTTP generado en la petición al API. Cuando
hay errores de petición o antes de generarla, este valor es igual a cero.
6. getRequestId(): código generado cuando se generó el error en el API. Cuando
hay errores de petición o antes de generarla, este valor es igual a cadena
vacía.
La implementación de errores se puede ejemplificar de la siguiente manera:
try {
Openpay::setId('moiep6umtcnanql3jrxp');
Openpay::setApiKey('sk_'); // esta línea generará un error debido a que el
// formato de la llave privada es incorrecto
Openpay::setSandboxMode(true);
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$customer->name = 'Juan';
$customer->last_name = 'Godinez';
$customer->save();
} catch (OpenpayApiTransactionError $e) {
error('ERROR en la transacción: ' . $e->getMessage() .
' [código de error: ' . $e->getErrorCode() .
', categoría de error: ' . $e->getCategory() .
', código HTTP: '. $e->getHttpCode() .
', id petición: ' . $e->getRequestId() . ']');
} catch (OpenpayApiRequestError $e) {
error('ERROR en la petición: ' . $e->getMessage());
} catch (OpenpayApiConnectionError $e) {
error('ERROR en la conexión al API: ' . $e->getMessage());
} catch (OpenpayApiAuthError $e) {
error('ERROR en la autenticación: ' . $e->getMessage());
} catch (OpenpayApiError $e) {
error('ERROR en el API: ' . $e->getMessage());
} catch (Exception $e) {
error('Error en el script: ' . $e->getMessage());
}
EJEMPLOS:
Clientes
Agregar Cliente:
$customerData = array(
'name' => 'Teofilo',
'last_name' => 'Velazco',
'email' => '[email protected]',
'phone_number' => '4421112233',
'address' => array(
'line1' => 'Av. 5 de Febrero No. 1',
'line2' => 'Col. Felipe Carrillo Puerto',
'line3' => 'Zona industrial Carrillo Puerto',
'postal_code' => '76920',
'state' => 'Querétaro',
'city' => 'Querétaro',
'country_code' => 'MX'));
$openpay = Openpay::getInstance();
$customer = $openpay->customers->add($customerData);
Obtener Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
Obtener listado de Clientes:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$customerList = $openpay->customers->getList($findData);
Actualización de datos del Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$customer->name = 'Juan';
$customer->last_name = 'Godinez';
$customer->save();
Eliminar Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$customer->delete();
Tarjetas:
Agregar tarjeta a Cliente:
$customerData = array(
'name' => 'Teofilo',
'last_name' => 'Velazco Pérez',
'email' => '[email protected]',
'phone_number' => '4421112233',
'address' => array(
'line1' => 'Av. 5 de Febrero No. 1',
'line2' => 'Col. Felipe Carrillo Puerto',
'line3' => 'Zona industrial Carrillo Puerto',
'postal_code' => '76920',
'state' => 'Querétaro',
'city' => 'Querétaro',
'country_code' => 'MX'));
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->add($cardData);
Obtener tarjeta de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->get('k9pn8qtsvr7k7gxoq1r5');
Obtener listado de tarjetas de Cliente:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$cardList = $customer->cards->getList($findData);
Eliminar tarjeta de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->get('k9pn8qtsvr7k7gxoq1r5');
$card->delete();
Agregar tarjeta a Merchant:
$openpay = Openpay::getInstance();
$card = $openpay->cards->add($cardData);
Obtener tarjeta de Merchant:
$openpay = Openpay::getInstance();
$card = $openpay->cards->get('k9pn8qtsvr7k7gxoq1r5');
Obtener listado de tarjetas de Merchant:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$cardList = $openpay->cards->getList($findData);
Eliminar tarjeta de Merchant:
$openpay = Openpay::getInstance();
$card = $openpay->cards->get('k9pn8qtsvr7k7gxoq1r5');
$card->delete();
Cuentas de Banco:
Agregar cuenta de banco a Cliente:
$bankData = array(
'clabe' => '072910007380090615',
'alias' => 'Cuenta principal',
'holder_name' => 'Teofilo Velazco');
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$bankaccount = $customer->bankaccounts->add($bankData);
Obtener cuenta de banco de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$bankaccount = $customer->bankaccounts->get('b4vcouaavwuvkpufh0so');
Obtener listado de cuentas de banco de Cliente:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$bankaccount = $customer->bankaccounts->getList($findData);
Eliminar cuenta de banco de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$bankaccount = $customer->bankaccounts->get('b4vcouaavwuvkpufh0so');
$bankaccount->delete();
Cargos:
Hacer cargo a Cliente:
$chargeData = array(
'source_id' => 'tvyfwyfooqsmfnaprsuk',
'method' => 'card',
'amount' => 100,
'description' => 'Cargo inicial a mi cuenta',
'order_id' => 'ORDEN-00070');
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$charge = $customer->charges->create($chargeData);
Obtener cargo de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$charge = $customer->charges->get('tvyfwyfooqsmfnaprsuk');
Obtener listado de cargos de Cliente:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$charge = $customer->charges->getList($findData);
Hacer devolucion de cargo a Cliente:
$refundData = array(
'description' => 'Reembolso' );
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$charge = $customer->charges->get('tvyfwyfooqsmfnaprsuk');
$charge->refund($refundData);
Hacer cargo a Merchant:
$chargeData = array(
'method' => 'card',
'source_id' => 'krfkkmbvdk3hewatruem',
'amount' => 100,
'description' => 'Cargo inicial a mi merchant',
'order_id' => 'ORDEN-00071');
$openpay = Openpay::getInstance();
$charge = $openpay->charges->create($chargeData);
debug($charge);
Obtener cargo de Merchant:
$openpay = Openpay::getInstance();
$charge = $openpay->charges->get('tvyfwyfooqsmfnaprsuk');
Obtener listado de cargos de Merchant:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$charge = $openpay->charges->getList($findData);
Hacer devolución de cargo a Merchant:
$refundData = array(
'description' => 'Devolución' );
$openpay = Openpay::getInstance();
$charge = $openpay->charges->get('tvyfwyfooqsmfnaprsuk');
$charge->refund($refundData);
Transferencias:
Hacer transferencia a Cliente:
$transferData = array(
'customer_id' => 'aqedin0owpu0kexr2eor',
'amount' => 12.50,
'description' => 'Cobro de Comisión',
'order_id' => 'ORDEN-00061');
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$transfer = $customer->transfers->create($transferData);
Obtener transferencia de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$transfer = $customer->transfers->get('tyxesptjtx1bodfdjmlb');
Obtener listado de transferencias a Cliente:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$transfer = $customer->transfers->getList($findData);
Pagos:
Hacer pago a Cliente:
$payoutData = array(
'method' => 'card',
'destination_id' => 'k9pn8qtsvr7k7gxoq1r5',
'amount' => 1000,
'description' => 'Retiro de saldo semanal',
'order_id' => 'ORDEN-00062');
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$payout = $customer->payouts->create($payoutData);
Obtener pago a Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$payout = $customer->payouts->get('tysznlyigrkwnks6eq2c');
Obtener listado de pagos a Cliente:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$payout = $customer->payouts->getList($findData);
Hacer pago a Merchant:
$payoutData = array(
'method' => 'card',
'destination_id' => 'krfkkmbvdk3hewatruem',
'amount' => 500,
'description' => 'Retiro de saldo semanal',
'order_id' => 'ORDEN-00072');
$openpay = Openpay::getInstance();
$payout = $openpay->payouts->create($payoutData);
Obtener pago a Merchant:
$openpay = Openpay::getInstance();
$payout = $openpay->payouts->get('t4tzkjspndtj9bnsop2i');
Obtener listado de pagos a Merchant:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$payout = $openpay->payouts->getList($findData);
Comisiones:
Hacer cobro de comisión a Cliente
$feeData = array(
'customer_id' => 'a9ualumwnrcxkl42l6mh',
'amount' => 12.50,
'description' => 'Cobro de Comisión',
'order_id' => 'ORDEN-00063');
$openpay = Openpay::getInstance();
$fee = $openpay->fees->create($feeData);
Obtener listadeo de comisiones de Cliente:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$fee = $openpay->fees->getList($findData);
Planes:
Agregar plan:
$planData = array(
'amount' => 150.00,
'status_after_retry' => 'cancelled',
'retry_times' => 2,
'name' => 'Plan Curso Verano',
'repeat_unit' => 'month',
'trial_days' => '30',
'repeat_every' => '1',
'currency' => 'MXN');
$openpay = Openpay::getInstance();
$plan = $openpay->plans->add($planData);
Obtener plan:
$openpay = Openpay::getInstance();
$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
Obtener listado de planes:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$plan = $openpay->plans->getList($findData);
debug($plan);
Actualizar plan:
$openpay = Openpay::getInstance();
$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
$plan->name = 'Plan Curso de Verano 2014';
$plan->save();
Eliminar plan:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
$plan->delete();
Obtener listado de suscriptores al plan:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$plan = $openpay->plans->get($planId);
$subscription = $plan->subscriptions->getList($findData);
Suscripciones:
Agregar suscripcion de Cliente:
$subscriptionData = array(
'trial_days' => '90',
'plan_id' => 'pduar9iitv4enjftuwyl',
'card_id' => 'konvkvcd5ih8ta65umie');
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->add($subscriptionData);
Obtener suscripción de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
Obtener listado de suscripciones de Cliente:
$findData = array(
'creation[gte]' => '2013-01-01',
'creation[lte]' => '2013-12-31',
'offset' => 0,
'limit' => 5);
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->getList($findData);
Actualizar suscripción de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
$subscription->trial_end_date = '2014-12-31';
$subscription->save();
Eliminar suscripción de Cliente:
$openpay = Openpay::getInstance();
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
$subscription->delete();