Płatności cykliczne – Deweloper: EDD_Subscription

Płatności cykliczne zawierają nową klasę EDD do zarządzania subskrypcjami. Klasa EDD_Subscription pozwala deweloperowi na programową pracę z subskrypcjami. Ten dokument wymieni właściwości, metody i sugerowaną funkcjonalność EDD_Subscription.

Właściwości

• $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;

Metody

• create( $data = array() )
• update( $args = array() )
• delete()
• get_original_payment_id()
• get_child_payments()
• get_total_payments()
• get_lifetime_value()
• dodaj_platnosc( $args = array() )
• odnow()
• zakoncz()
• wygasnij()
• nieudana()
• anuluj()
• mozna_anulowac()
• pobierz_url_anulowania()
• mozna_aktualizowac()
• pobierz_url_aktualizacji()
• jest_aktywny()
• jest_po_terminie()
• pobierz_termin_waznosci()
• pobierz_czas_wygasniecia()
• pobierz_status()
• pobierz_etykiete_statusu()
• istnieje_platnosc( $txn_id = ” )

Użycie

Podstawowa instancjacja

Obiekt EDD_Subscription "pusty" może zostać utworzony za pomocą tego kodu:

$subscription = new EDD_Subscription();

Zwróci to obiekt o następującej strukturze:

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] => 
)

Instancjowanie istniejącej subskrypcji

Konstruktor EDD_Subscription akceptuje 2 argumenty. Pierwszy to identyfikator subskrypcji (liczba całkowita) lub, jeśli drugi argument jest prawdziwy, pierwszy może być identyfikatorem profilu subskrypcji.

Identyfikator subskrypcji można znaleźć w adresie URL podczas przeglądania subskrypcji.

Identyfikator profilu można znaleźć na liście podczas przeglądania subskrypcji.

Te dwie linie kodu zwrócą ten sam wynik, ponieważ odnoszą się do tej samej subskrypcji:

$subscription = new EDD_Subscription( 3 );

$subscription = new EDD_Subscription( 'sub_85YmWtzABSAWN7', true );

Powyższe linie kodu zwrócą obiekt podobny do tego:

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
                )

        )

)

Modyfikacja obiektu

Używając dołączonych metod, można zrobić prawie wszystko z subskrypcją.

O ile nie zaznaczono inaczej, każdy podany przykład metody będzie używał tego modelu instancjacji:

$subscription = new EDD_Subscription();

Metody operacyjne

EDD_Subscription zawiera metody do tworzenia, usuwania, aktualizowania i odnawiania subskrypcji, a także dodawania płatności.

$subskrypcja->utworz()

Aby poprawnie utworzyć subskrypcję, musisz przekazać pewne informacje. Te elementy są wymagane:

$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
);

Następnie możesz wywołać metodę create() z tymi informacjami.

$subscription->create( $data );

Metoda create() zwraca obiekt z tymi samymi danymi, które uzyskałbyś, zapytując o konkretny identyfikator subskrypcji.

 

$subscription->update()

Aktualizacja subskrypcji wykorzystuje metodę update() z dowolnym podzbiorem opcji tablicy użytych dla metody create(). Metoda update() wymaga również identyfikatora subskrypcji. Coś takiego zadziała:

$data = array(
    'expiration' => '2019-07-17 23:59:59',
);
$subscription->update( $data );

 

$subscription->delete()

Metoda delete() akceptuje identyfikator subskrypcji i trwale usuwa subskrypcję ze sklepu EDD. Należy pamiętać, że nie wpływa to na subskrypcje zarejestrowane w bramkach płatności. Te powinny być obsługiwane indywidualnie.

$subscription->renew()

Ta metoda odnawia subskrypcję, przedłużając ją o jeden okres poza bieżącą datą wygaśnięcia.

$subscription->add_payment( $args = array() )

Ta metoda pozwala na dokonanie płatności. Akceptuje tablicę i wymaga tych trzech elementów tablicy:

• amount: kwota pieniędzy podlegająca płatności
• transaction_id: identyfikator transakcji subskrypcji z bramki płatności. Przykład: ‘ch_17q04L4NqFpaKRwY8ucZjW3t’
• gateway: bramka płatności użyta dla subskrypcji. Przykład: ‘stripe’

Po pomyślnym wykonaniu add_payment() zwraca true.

Uzyskiwanie informacji o subskrypcji

EDD_Subscription udostępnia szereg metod do uzyskiwania informacji o subskrypcji.

$subscription->get_original_payment_id()

Ta metoda zwraca liczbę całkowitą, która jest identyfikatorem oryginalnej płatności. W interfejsie użytkownika tę płatność można znaleźć w sekcji Pobrania → Historia płatności.

$subscription->get_child_payments()

Metoda zwraca tablicę obiektów EDD_Payment, gdzie każdy obiekt jest płatnością podrzędną. Obiekty będą wyglądać mniej więcej tak:

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()

Ta metoda zwraca liczbę całkowitą, która jest liczbą wszystkich dokonanych płatności, w tym płatności początkowych i wszystkich płatności podrzędnych.

$subscription->get_lifetime_value()

Ta metoda zwraca liczbę zmiennoprzecinkową, która jest łączną kwotą pieniężną wszystkich kiedykolwiek dokonanych płatności.

$subscription->get_cancel_url()

Ta metoda zwróci adres URL do anulowania subskrypcji, który jest przetwarzany przez bramkę, za pośrednictwem której subskrypcja została zakupiona.

$subscription->get_update_url()

Ta metoda zwróci adres URL do aktualizacji subskrypcji, który jest przetwarzany przez bramkę, za pośrednictwem której subskrypcja została zakupiona.

$subscription->get_expiration()

Zwraca datę i godzinę wygaśnięcia subskrypcji w tym formacie:

2016-04-15 23:59:59

$subscription->get_expiration_time()

Ta metoda zwraca liczbę całkowitą, która jest znacznikiem czasu Unix wygaśnięcia.

$subscription->get_status()

Ta metoda zwraca bieżący status subskrypcji w formacie użytecznym dla kodu. Opcje to: ‘pending’, ‘active’, ‘cancelled’, ‘expired’, ‘failing’, ‘completed’.

$subscription->get_status_label()

Ta metoda zwraca bieżący status subskrypcji w formacie użytecznym do prezentacji. Opcje to: ‘Pending’, ‘Active’, ‘Cancelled’, ‘Expired’, ‘Failing’, ‘Completed’.

Warunki subskrypcji

EDD_Subscription oferuje szereg metod warunkowych.

$subscription->can_cancel()

Ta metoda zwraca wartość logiczną i jest filtrowana przez bramki płatności, aby zwrócić wartość true dla subskrypcji, które można anulować za pomocą identyfikatora profilu u procesora płatności.

$subscription->can_update()

Ta metoda zwraca wartość logiczną i jest filtrowana przez bramki płatności, aby zwrócić wartość true, jeśli subskrypcja może mieć zaktualizowaną metodę płatności. Służy wyłącznie do określenia, czy metoda płatności może zostać zaktualizowana.

$subscription->is_active()

 

$subscription->is_expired()

$subscription->payment_exists( $txn_id = ” )

Ta metoda akceptuje identyfikator transakcji utworzony przez bramkę płatności. Oto przykład identyfikatora transakcji subskrypcji ze Stripe:

ch_17q04L4NqFpaKRwY8ucZjW3t

Ta metoda zwraca wartość logiczną, true, jeśli znajdzie transakcję z podanym identyfikatorem.

Metody statusu

Ta metoda zmienia status subskrypcji na ‘complete’.

$subscription->expire()

Ta metoda zmienia status subskrypcji na ‘expired’.

$subscription->failing()

Ta metoda zmienia status subskrypcji na ‘failing’.

$subscription->cancel()

Ta metoda zmienia status subskrypcji na ‘cancelled’.