Tabla de Contenidos
Pagos recurrentes – viene con una nueva clase EDD para administrar suscripciones. La clase EDD_Subscription permite a un desarrollador trabajar con suscripciones mediante programación. Este documento enumerará las propiedades, métodos y la funcionalidad sugerida de EDD_Subscription.
Propiedades
- $id = 0;
- $customer_id = 0;
- $period = "";
- $initial_amount = "";
- $recurring_amount = "";
- $bill_times = 0;
- $parent_payment_id = 0;
- $product_id = 0;
- $created = '0000-00-00 00:00:00';
- $expiration = '0000-00-00 00:00:00';
- $status = 'pending';
- $profile_id = "";
- $gateway = "";
- $customer;
Métodos
- create( $data = array() )
- update( $args = array() )
- delete()
- get_original_payment_id()
- get_child_payments()
- get_total_payments()
- get_lifetime_value()
- add_payment( $args = array() )
- renew()
- complete()
- expire()
- failing()
- cancel()
- can_cancel()
- get_cancel_url()
- can_update()
- get_update_url()
- is_active()
- is_expired()
- get_expiration()
- get_expiration_time()
- get_status()
- get_status_label()
- payment_exists($txn_id = ”)
Uso
Instanciación básica
Un objeto EDD_Subscription "vacío" puede ser creado con este código:
$subscription = new EDD_Subscription();
Esto devolverá un objeto con esta estructura:
EDD_Subscription Object
(
[subs_db:EDD_Subscription:private] => EDD_Subscriptions_DB Object
(
[table_name] => wp_edd_subscriptions
[version] => 1.0
[primary_key] => id
)
[id] => 0
[customer_id] => 0
[period] =>
[initial_amount] =>
[recurring_amount] =>
[bill_times] => 0
[parent_payment_id] => 0
[product_id] => 0
[created] => 0000-00-00 00:00:00
[expiration] => 0000-00-00 00:00:00
[status] => pending
[profile_id] =>
[gateway] =>
[customer] =>
)
Instanciando una suscripción existente
El constructor de EDD_Subscription acepta 2 argumentos. El primero es un entero que representa un ID de suscripción o, si el segundo argumento es verdadero, el primero puede ser un profile_id de suscripción.
Puedes encontrar un ID de suscripción en la URL mientras ves una suscripción. 
Puedes encontrar el ID del perfil listado al ver una suscripción. 
Estas dos líneas de código devolverán el mismo resultado porque se refieren a la misma suscripción:
$subscription = new EDD_Subscription( 3 );
$subscription = new EDD_Subscription( 'sub_85YmWtzABSAWN7', true );
Las líneas de código anteriores devolverían cada una un objeto como este:
EDD_Subscription Object
(
[subs_db:EDD_Subscription:private] => EDD_Subscriptions_DB Object
(
[table_name] => wp_edd_subscriptions
[version] => 1.0
[primary_key] => id
)
[id] => 1
[customer_id] => 3
[period] => month
[initial_amount] => 50.00
[recurring_amount] => 50.00
[bill_times] => 0
[parent_payment_id] => 87
[product_id] => 85
[created] => 2016-03-15 15:36:30
[expiration] => 2016-04-15 23:59:59
[status] => pending
[profile_id] => paypal-363e3cc178dab152bb59b958024bce75
[gateway] => paypal
[customer] => EDD_Customer Object
(
[id] => 3
[purchase_count] => 3
[purchase_value] => 110.000000
[email] => [email protected]
[name] => Bob Smith
[date_created] => 2016-03-08 15:01:02
[payment_ids] => 54,63,87,88,91
[user_id] => 2
[notes] => Array
(
[0] => March 16, 2016 14:37:22 - Subscription #3 cancelled admin
)
[db:protected] => EDD_DB_Customers Object
(
[table_name] => wp_edd_customers
[version] => 1.0
[primary_key] => id
)
)
)
Modificación de objeto
Usando los métodos incluidos, casi cualquier cosa puede hacerse con una suscripción.
A menos que se indique lo contrario, cada ejemplo de método dado usará este modelo de instanciación:
$subscription = new EDD_Subscription();
Métodos operativos
EDD_Subscription incluye métodos para crear, eliminar, actualizar y renovar suscripciones, así como para agregar pagos.
$subscription->create()
Para crear una suscripción correctamente, necesitas pasar cierta información. Estos elementos son obligatorios:
$data = array(
'customer_id' => 0, // an integer, should be a valid customer_id
'period' => '', // accepts 'day', 'week', 'month', or 'year'; how often the subscription renews
'initial_amount' => '', // accepts a float
'recurring_amount' => '', // accepts a float
'bill_times' => 0, // accepts an integer; the number of times billing should happen, 0 means indefinite
'parent_payment_id' => 0, // accepts an integer; the payment id returned by the initial payment
'product_id' => 0, // accepts an integer; the id of the product
'created' => '', // accepts a date string; formatted like 0000-00-00 00:00:00
'expiration' => '', // accepts a date string; formatted like 0000-00-00 00:00:00
'status' => '', // accepts 'Pending', 'Active', 'Cancelled', 'Expired', 'Failing', 'Completed'
'profile_id' => '', // accepts a string returned by the payment gateway as their subscription ID
);
Luego puedes llamar al método create() con esa información.
$subscription->create( $data );
El método create() devuelve un objeto con los mismos datos que obtendrías al consultar un ID de suscripción específico.
$subscription->update()
La actualización de una suscripción utiliza el método update() con cualquier subconjunto de las opciones de array utilizadas para el método create(). El método update() también requiere un ID de suscripción. Algo como esto funcionaría:
$data = array(
'expiration' => '2019-07-17 23:59:59',
);
$subscription->update( $data );
$subscription->delete()
El método delete() acepta un ID de suscripción y elimina permanentemente la suscripción de la tienda EDD. Ten en cuenta que esto no afecta a las suscripciones registradas en las Pasarelas de Pago. Esas deben manejarse individualmente.
$subscription->renew()
Este método renueva una suscripción, extendiéndola por un período más allá de la fecha de expiración actual.
$subscription->add_payment($args = array())
Este método te permite realizar un pago. Acepta un array y requiere estos tres elementos del array:
- amount: la cantidad de dinero que se está pagando
- transaction_id: el ID de transacción de la suscripción de la pasarela de pago. Ejemplo: ‘ch_17q04L4NqFpaKRwY8ucZjW3t’
- gateway: la pasarela de pago utilizada para la suscripción. Ejemplo: ‘stripe’
En caso de éxito, add_payment() devuelve true.
Obtener información de suscripción
EDD_Subscription proporciona una serie de métodos para obtener información sobre una suscripción.
$subscription->get_original_payment_id()
Este método devuelve un entero que es el ID del pago original. En la Interfaz de Usuario, este Pago se puede encontrar en Descargas → Historial de Pagos.
$subscription->get_child_payments()
El método devuelve un array de objetos EDD_Payment donde cada objeto es un pago hijo. Los objetos se verán algo así:
Array
(
[0] => EDD_Payment Object
(
[ID] => 1111111
[_ID:protected] => 1111111
[new:protected] =>
[number:protected] => 1111111
[mode:protected] => live
[key:protected] => 8d6f842jkf66cb6312117b9ad417dc6be
[total:protected] => 57.4
[subtotal:protected] => 57.4
[tax:protected] => 0
[discounted_amount:protected] => 0
[tax_rate:protected] =>
[fees:protected] => Array
(
)
[fees_total:protected] => 0
[discounts:protected] => samplediscount
[date:protected] => 2018-05-17 06:40:29
[completed_date:protected] =>
[status:protected] => edd_subscription
[post_status:protected] => edd_subscription
[old_status:protected] =>
[status_nicename:protected] => Renewal
[customer_id:protected] => 111111
[user_id:protected] => 1nan1
[first_name:protected] => Bob Smith
[last_name:protected] => Smith
[email:protected] => [email protected]
[user_info:EDD_Payment:private] => Array
(
[first_name] => Bob Smith
[last_name] => Smith
[discount] => samplediscount
[id] => 1nan1
[email] => [email protected]
[address] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
)
[payment_meta:EDD_Payment:private] => Array
(
[key] => 8d6f842jkf66cb6312117b9ad417dc6be
[email] => [email protected]
[date] => 2018-05-17 06:40:29
[user_info] => Array
(
[first_name] => Bob Smith
[discount] => samplediscount
[id] => 1nan1
[email] => [email protected]
[address] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
)
[downloads] => Array
(
[0] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
)
[cart_details] => Array
(
[0] => Array
(
[name] => Sample Product
[id] => 1234
[item_number] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
[item_price] => 57.4
[quantity] => 1
[discount] => 0
[subtotal] => 57.4
[tax] => 0
[fees] => Array
(
)
[price] => 57.4
)
)
[fees] => Array
(
)
[currency] => USD
)
[address:protected] => Array
(
[line1] =>
[line2] =>
[city] =>
[country] =>
[state] =>
[zip] =>
[vat] =>
[notes] =>
)
[transaction_id:protected] => 7M999999999999999
[downloads:protected] => Array
(
[0] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
)
[ip:protected] => 192.168.1.1
[gateway:protected] => paypalexpress
[currency:protected] => USD
[cart_details:protected] => Array
(
[0] => Array
(
[name] => Sample Product
[id] => 1234
[item_number] => Array
(
[id] => 1234
[quantity] => 1
[options] => Array
(
[quantity] => 1
[price_id] => 0
)
)
[item_price] => 57.4
[quantity] => 1
[discount] => 0
[subtotal] => 57.4
[tax] => 0
[fees] => Array
(
)
[price] => 57.4
)
)
[has_unlimited_downloads:protected] =>
[pending:EDD_Payment:private] => Array
(
)
[parent_payment:protected] => 830936
)
)
$subscription->get_total_payments()
Este método devuelve un entero que es el recuento del número total de pagos realizados, incluyendo los pagos iniciales más todos los pagos hijos.
$subscription->get_lifetime_value()
Este método devuelve un float que es el total monetario de todos los pagos realizados.
$subscription->get_cancel_url()
Este método devolverá una URL para cancelar una suscripción que se procesa a través de la pasarela por la cual se compró la suscripción.
$subscription->get_update_url()
Este método devolverá una URL para actualizar una suscripción que se procesa a través de la pasarela por la cual se compró la suscripción.
$subscription->get_expiration()
Devuelve la fecha y hora en que la suscripción expirará en este formato:
2016-04-15 23:59:59
$subscription->get_expiration_time()
Este método devuelve un entero que es una marca de tiempo Unix de la expiración.
$subscription->get_status()
Este método devuelve el estado actual de una suscripción en un formato útil para el código. Las opciones son 'pending', 'active', 'cancelled', 'expired', 'failing', 'completed'.
$subscription->get_status_label()
Este método devuelve el estado actual de una suscripción en un formato útil para la presentación. Las opciones son 'Pendiente', 'Activa', 'Cancelada', 'Expirada', 'Fallida', 'Completada'.
Condicionales de suscripción
EDD_Subscription ofrece una serie de métodos condicionales.
$subscription->can_cancel()
Este método devuelve un booleano y es filtrado por las pasarelas de pago para devolver true en suscripciones que se pueden cancelar con un ID de perfil a través del procesador de pagos.
$subscription->can_update()
Este método devuelve un booleano y es filtrado por las pasarelas de pago para devolver true si la suscripción puede actualizar su método de pago. Es solo para determinar si se puede actualizar un método de pago.
$subscription->is_active()
y el estado es
ya sea 'active' o 'cancelled'.
$subscription->is_expired()
$subscription->payment_exists( $txn_id = ” )
Este método acepta un ID de transacción que ha sido creado por una pasarela de pago. Aquí hay un ejemplo de un ID de transacción de suscripción de Stripe:
ch_17q04L4NqFpaKRwY8ucZjW3t
Este método devuelve un booleano, true si encuentra una transacción con el ID proporcionado.
Métodos de estado
$subscription->complete()
Este método cambia el estado de una suscripción a 'complete'.
$subscription->expire()
Este método cambia el estado de una suscripción a 'expired'.
$subscription->failing()
Este método cambia el estado de una suscripción a 'failing'.
$subscription->cancel()
Este método cambia el estado de una suscripción a 'cancelled'.
