Inhoudsopgave
Terugkerende Betalingen wordt geleverd met een nieuwe EDD-klasse voor het beheren van abonnementen. De EDD_Subscription-klasse stelt een ontwikkelaar in staat om programmatisch met abonnementen te werken. Dit document bevat de eigenschappen, methoden en voorgestelde functionaliteit van EDD_Subscription.
Eigenschappen
- $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;
Methoden
- 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 = ” )
Gebruik
Basisinstantiatie
Een “leeg” EDD_Subscription object kan met deze code worden aangemaakt:
$subscription = new EDD_Subscription();
Dit retourneert een object met deze structuur:
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] =>
)
Instantiëren van een Bestaande Abonnement
De EDD_Subscription constructor accepteert 2 argumenten. Het eerste is ofwel een integer die een abonnement ID vertegenwoordigt, ofwel, als het tweede argument waar is, dan kan het eerste een abonnement profile_id zijn.
Je kunt een abonnement ID vinden in de URL terwijl je een abonnement bekijkt. 
Je kunt de profiel ID vinden die wordt weergegeven bij het bekijken van een abonnement. 
Deze twee regels code retourneren dezelfde uitvoer omdat ze verwijzen naar hetzelfde abonnement:
$subscription = new EDD_Subscription( 3 );
$subscription = new EDD_Subscription( 'sub_85YmWtzABSAWN7', true );
De bovenstaande regels code zouden elk een object als dit retourneren:
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
)
)
)
Objectwijziging
Met de meegeleverde methoden kan bijna alles met een abonnement worden gedaan.
Tenzij anders vermeld, zullen alle gegeven methodevoorbeelden dit instantiatiemodel gebruiken:
$subscription = new EDD_Subscription();
Operationele Methoden
EDD_Subscription bevat methoden voor het aanmaken, verwijderen, bijwerken en vernieuwen van abonnementen, evenals het toevoegen van betalingen.
$subscription->create()
Om een abonnement correct aan te maken, moet u wat informatie doorgeven. Deze gegevens zijn vereist:
$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
);
Vervolgens kunt u de create() methode aanroepen met die informatie.
$subscription->create( $data );
De create() methode retourneert een object met dezelfde gegevens die u zou krijgen door een specifieke abonnements-ID op te vragen.
$subscription->update()
Het updaten van een abonnement maakt gebruik van de update() methode met een deelverzameling van de array-opties die voor de create() methode worden gebruikt. De update() methode vereist ook een abonnements-ID. Iets als dit zou werken:
$data = array(
'expiration' => '2019-07-17 23:59:59',
);
$subscription->update( $data );
$subscription->delete()
De delete() methode accepteert een abonnements-ID en verwijdert het abonnement permanent uit de EDD-winkel. Merk op dat dit geen invloed heeft op abonnementen die zijn geregistreerd bij betaalpoorten. Die moeten individueel worden afgehandeld.
$subscription->renew()
Deze methode vernieuwt een abonnement en verlengt het met één periode na de huidige vervaldatum.
$subscription->add_payment( $args = array() )
Deze methode stelt u in staat om een betaling te doen. Het accepteert een array en vereist deze drie array-elementen:
- amount: het te betalen geldbedrag
- transaction_id: de transactie-ID van het abonnement van de betaalpoort. Voorbeeld: ‘ch_17q04L4NqFpaKRwY8ucZjW3t’
- gateway: de betaalpoort die voor het abonnement is gebruikt. Voorbeeld: ‘stripe’
Bij succes retourneert add_payment() true.
Abonnementsinformatie Ophalen
EDD_Subscription biedt een aantal methoden om informatie over een abonnement te verkrijgen.
$subscription->get_original_payment_id()
Deze methode retourneert een geheel getal dat de ID is van de oorspronkelijke betaling. In de gebruikersinterface kan deze betaling worden gevonden onder Downloads → Betalingsgeschiedenis.
$subscription->get_child_payments()
De methode retourneert een array van EDD_Payment-objecten waarbij elk object een kindbetaling is. De objecten zullen er ongeveer zo uitzien:
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()
Deze methode retourneert een geheel getal dat een telling is van het totale aantal gedane betalingen, inclusief de initiële betalingen plus alle kindbetalingen.
$subscription->get_lifetime_value()
Deze methode retourneert een float die het monetaire totaal is van alle ooit gedane betalingen.
$subscription->get_cancel_url()
Deze methode retourneert een URL voor het annuleren van een abonnement dat wordt verwerkt door de poort waarmee het abonnement is aangeschaft.
$subscription->get_update_url()
Deze methode retourneert een URL voor het bijwerken van een abonnement dat wordt verwerkt door de poort waarmee het abonnement is aangeschaft.
$subscription->get_expiration()
Retourneert de datum en tijd waarop het abonnement zal verlopen in dit formaat:
2016-04-15 23:59:59
$subscription->get_expiration_time()
Deze methode retourneert een geheel getal dat een Unix-tijdstempel van de vervaldatum is.
$subscription->get_status()
Deze methode retourneert de huidige status van een abonnement in een voor code bruikbaar formaat. Opties zijn ‘pending’, ‘active’, ‘cancelled’, ‘expired’, ‘failing’, ‘completed’.
$subscription->get_status_label()
Deze methode retourneert de huidige status van een abonnement in een voor presentatie bruikbaar formaat. Opties zijn ‘Pending’, ‘Active’, ‘Cancelled’, ‘Expired’, ‘Failing’, ‘Completed’.
Abonnementsvoorwaarden
EDD_Subscription biedt een aantal conditionele methoden.
$subscription->can_cancel()
Deze methode retourneert een boolean en wordt gefilterd door betalingsgateways om true te retourneren voor abonnementen die geannuleerd kunnen worden met een profiel-ID via de merchant processor.
$subscription->can_update()
Deze methode retourneert een boolean en wordt gefilterd door betalingsgateways om true te retourneren als de betaalmethode van het abonnement kan worden bijgewerkt. Het is *alleen* bedoeld om te bepalen of een betaalmethode kan worden bijgewerkt.
$subscription->is_active()
*en* de status
*ofwel* ‘active’ of ‘cancelled’ is.
$subscription->is_expired()
$subscription->payment_exists( $txn_id = ” )
Deze methode accepteert een transactie-ID dat is aangemaakt door een betalingsgateway. Hier is een voorbeeld van een abonnements-transactie-ID van Stripe:
ch_17q04L4NqFpaKRwY8ucZjW3t
Deze methode retourneert een boolean, true als het een transactie met de opgegeven ID vindt.
Statusmethoden
$subscription->complete()
Deze methode wijzigt de status van een abonnement naar ‘complete’.
$subscription->expire()
Deze methode wijzigt de status van een abonnement naar ‘expired’.
$subscription->failing()
Deze methode wijzigt de status van een abonnement naar ‘failing’.
$subscription->cancel()
Deze methode wijzigt de status van een abonnement naar ‘cancelled’.
