Sumário
Pagamentos Recorrentes vem com uma nova classe EDD para gerenciar assinaturas. A classe EDD_Subscription permite que um desenvolvedor trabalhe com assinaturas programaticamente. Este documento listará as propriedades, métodos e funcionalidades sugeridas da EDD_Subscription.
Propriedades
- $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()
- adicionar_pagamento( $args = array() )
- renovar()
- completar()
- expirar()
- falhando()
- cancelar()
- pode_cancelar()
- obter_url_cancelamento()
- pode_atualizar()
- obter_url_atualizacao()
- esta_ativo()
- esta_expirado()
- obter_expiracao()
- obter_tempo_expiracao()
- obter_status()
- obter_rotulo_status()
- pagamento_existe( $txn_id = ” )
Uso
Instanciação Básica
Um objeto EDD_Subscription "vazio" pode ser criado com este código:
$subscription = new EDD_Subscription();
Isso retornará um objeto com esta estrutura:
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 uma Assinatura Existente
O construtor EDD_Subscription aceita 2 argumentos. O primeiro é um inteiro representando um ID de assinatura ou, se o segundo argumento for verdadeiro, o primeiro pode ser um profile_id de assinatura.
Você pode encontrar um ID de assinatura na URL ao visualizar uma assinatura. 
Você pode encontrar o ID do perfil listado ao visualizar uma assinatura. 
Essas duas linhas de código retornarão a mesma saída porque se referem à mesma assinatura:
$subscription = new EDD_Subscription( 3 );
$subscription = new EDD_Subscription( 'sub_85YmWtzABSAWN7', true );
As linhas de código acima retornariam cada uma um 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
)
)
)
Modificação de Objeto
Usando os métodos incluídos, quase tudo pode ser feito com uma assinatura.
A menos que declarado de outra forma, todos os exemplos de métodos fornecidos usarão este modelo de instanciação:
$subscription = new EDD_Subscription();
Métodos Operacionais
EDD_Subscription inclui métodos para criar, excluir, atualizar e renovar assinaturas, bem como adicionar pagamentos.
$assinatura->criar()
Para criar uma assinatura corretamente, você precisa fornecer algumas informações. Estes itens são obrigatórios:
$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
);
Em seguida, você pode chamar o método create() com essas informações.
$subscription->create( $data );
O método create() retorna um objeto com os mesmos dados que você obteria consultando um ID de assinatura específico.
$subscription->update()
A atualização de uma assinatura usa o método update() com qualquer subconjunto das opções de array usadas para o método create(). O método update() também requer um ID de assinatura. Algo como isto funcionaria:
$data = array(
'expiration' => '2019-07-17 23:59:59',
);
$subscription->update( $data );
$subscription->delete()
O método delete() aceita um ID de assinatura e remove permanentemente a assinatura da loja EDD. Observe que isso não afeta as assinaturas registradas nos Gateways de Pagamento. Essas devem ser tratadas individualmente.
$subscription->renew()
Este método renova uma assinatura, estendendo-a por um período além da data de expiração atual.
$subscription->add_payment( $args = array() )
Este método permite que você faça um pagamento. Ele aceita um array e requer estes três elementos do array:
- amount: o valor em dinheiro que está sendo pago
- transaction_id: o ID da transação da assinatura do gateway de pagamento. Exemplo: ‘ch_17q04L4NqFpaKRwY8ucZjW3t’
- gateway: o gateway de pagamento usado para a assinatura. Exemplo: ‘stripe’
Em caso de sucesso, add_payment() retorna true.
Obtendo Informações da Assinatura
EDD_Subscription fornece vários métodos para obter informações sobre uma assinatura.
$subscription->get_original_payment_id()
Este método retorna um inteiro que é o ID do pagamento original. Na Interface do Usuário, este Pagamento pode ser encontrado em Downloads → Histórico de Pagamentos.
$subscription->get_child_payments()
O método retorna um array de objetos EDD_Payment onde cada objeto é um pagamento filho. Os objetos se parecerão com algo assim:
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 retorna um inteiro que é a contagem do número total de pagamentos feitos, incluindo os pagamentos iniciais mais todos os pagamentos filhos.
$subscription->get_lifetime_value()
Este método retorna um float que é o total monetário de todos os pagamentos já feitos.
$subscription->get_cancel_url()
Este método retornará uma URL para cancelar uma assinatura que é processada pelo gateway através do qual a assinatura foi comprada.
$subscription->get_update_url()
Este método retornará uma URL para atualizar uma assinatura que é processada pelo gateway através do qual a assinatura foi comprada.
$subscription->get_expiration()
Retorna a data e hora em que a assinatura expirará neste formato:
2016-04-15 23:59:59
$subscription->get_expiration_time()
Este método retorna um inteiro que é um timestamp Unix da expiração.
$subscription->get_status()
Este método retorna o status atual de uma assinatura em um formato útil para código. As opções são ‘pending’, ‘active’, ‘cancelled’, ‘expired’, ‘failing’, ‘completed’.
$subscription->get_status_label()
Este método retorna o status atual de uma assinatura em um formato útil para apresentação. As opções são ‘Pendente’, ‘Ativa’, ‘Cancelada’, ‘Expirada’, ‘Falhando’, ‘Concluída’.
Condicionais de Assinatura
EDD_Subscription oferece vários métodos condicionais.
$subscription->can_cancel()
Este método retorna um booleano e é filtrado por gateways de pagamento para retornar true em assinaturas que podem ser canceladas com um ID de perfil através do processador de pagamento.
$subscription->can_update()
Este método retorna um booleano e é filtrado por gateways de pagamento para retornar true se a assinatura puder ter seu método de pagamento atualizado. É apenas para determinar se um método de pagamento pode ser atualizado.
$subscription->is_active()
e o status for
ou ‘active’ ou ‘cancelled’.
$subscription->is_expired()
$subscription->payment_exists( $txn_id = ” )
Este método aceita um ID de transação que foi criado por um gateway de pagamento. Aqui está um exemplo de um ID de transação de assinatura do Stripe:
ch_17q04L4NqFpaKRwY8ucZjW3t
Este método retorna um booleano, true se encontrar uma transação com o ID fornecido.
Métodos de Status
$subscription->complete()
Este método altera o status de uma assinatura para ‘complete’.
$subscription->expire()
Este método altera o status de uma assinatura para ‘expired’.
$subscription->failing()
Este método altera o status de uma assinatura para ‘failing’.
$subscription->cancel()
Este método altera o status de uma assinatura para ‘cancelled’.
