# Webhook, teljesítés és időtúllépési visszaigazolás

> A kézi webhook-beállítás, a nem található bejegyzés állapotkódja, a teljesítési horog, az időtúllépési visszaigazolás, valamint a Stripe-események és az aláírási titok módosítása.

Ez a fejezet hat horgot (hookot) mutat be, amelyekkel a Stripe-webhookok kezelését és a fizetés lezárulása utáni lépéseket szabhatod testre. A kódot az aktív téma `functions.php` fájljába, saját funkcióbővítő bővítménybe, saját Add-On-ba vagy kódrészlet-kezelő bővítménybe (snippets plugin) teheted.

## `gform_stripe_manual_webhook_configuration`: kézi webhook-beállítás

Ha a webhookokat magad hozod létre a Stripe vezérlőpultján, és a Gravity Formsban csak az aláírási titkokat (signing secret) akarod megadni, ezzel a szűrővel kapcsolhatod be a kézi beállítást. Bekapcsolás után a Stripe beállításai között a titkok közvetlenül beírhatók.

```php
add_filter( 'gform_stripe_manual_webhook_configuration', 'your_function_name' );
```

| Paraméter | Típus | Jelentés |
|---|---|---|
| `$manual_webhook_configuration` | boolean | Alapértéke `false`. `true` visszaadásával a kézi beállítás bekapcsol. |

Példa, amely mindenhol bekapcsolja:

```php
add_filter( 'gform_stripe_manual_webhook_configuration', '__return_true' );
```

## `gform_stripe_entry_not_found_status_code`: a „nem található bejegyzés” állapotkódja

Ha a Stripe webhookja olyan eseményt küld, amelyhez nem található bejegyzés, a bővítmény egy `WP_Error`-t ad vissza. Ennek a HTTP-állapotkódját írhatod felül a szűrővel. Az alapérték 200.

```php
add_filter( 'gform_stripe_entry_not_found_status_code', 'your_function_name', 10, 3 );
```

| Paraméter | Típus | Jelentés |
|---|---|---|
| `$status_code` | int | Az állapotkód. Alapértéke 200. |
| `$action` | array | Az esemény adatait tartalmazó asszociatív tömb. |
| `$event` | Stripe Event Object | A beérkezett webhookhoz tartozó Stripe-esemény objektuma. |

Példa:

```php
add_filter( 'gform_stripe_entry_not_found_status_code', 'change_status_code', 10, 3 );
function change_status_code( $status_code, $action, $event ) {
    return 205;
}
```

## `gform_stripe_fulfillment`: teljesítés a Checkout munkamenet lezárulása után

Ez nem szűrő, hanem akcióhorog (`do_action`). Akkor fut le, amikor egy Stripe Checkout munkamenet (session) sikeresen befejeződött, és egyedi műveleteket végezhetsz vele.

```php
add_action( 'gform_stripe_fulfillment', 'your_function_name', 10, 4 );
```

| Paraméter | Típus | Jelentés |
|---|---|---|
| `$session` | array | A Stripe-munkamenet objektuma. |
| `$entry` | array | A bejegyzés. |
| `$feed` | array | A feldolgozott feed. |
| `$form` | array | Az űrlap. |

Példa: értesítés az oldal adminisztrátorának a sikeres Checkout-fizetésről:

```php
add_action( 'gform_stripe_fulfillment', 'notify_on_checkout_success', 10, 4 );
function notify_on_checkout_success( $session, $entry, $feed, $form ) {
    $admin_email = get_bloginfo( 'admin_email' );
    wp_mail( $admin_email, 'A Stripe Checkout fizetés sikeres', 'Üzenet a sikeres fizetésről' );
}
```

## `gform_stripe_default_timeout_confirmation`: az időtúllépési visszaigazolás módosítása

Ha a Stripe-fizetés lezárása a vártnál tovább tart, az űrlap egy alapértelmezett időtúllépési visszaigazolást jelenít meg. A szűrővel ennek a tulajdonságait módosíthatod.

```php
add_filter( 'gform_stripe_default_timeout_confirmation', 'your_function_name', 10, 3 );
```

| Paraméter | Típus | Jelentés |
|---|---|---|
| `$timeout_confirmation` | array | Az időtúllépési visszaigazolás tulajdonságai. |
| `$form` | Form Object | A feldolgozott űrlap. |
| `$feed` | Feed Object | A feldolgozott feed. |

A visszaigazolás tömbjének alapértelmezett kulcsai:

| Kulcs | Alapérték |
|---|---|
| `id` | egyedi azonosító (`uniqid()`) |
| `name` | „Timeout Confirmation” (a bővítmény fordítható szövege) |
| `type` | `message` |
| `message` | A fizetés befejezése a vártnál tovább tart, kérdés esetén vedd fel velünk a kapcsolatot. |
| `disableAutoformat` | `false` |
| `page`, `url`, `queryString` | üres |
| `confirmation_conditional_logic` | `1` (be van kapcsolva) |
| `confirmation_conditional_logic_object` és `conditionalLogic` | Megjelenítés, ha minden szabály teljesül: a `payment_status` mező értéke „Processing”. |

Példa: az üzenet cseréje:

```php
add_filter( 'gform_stripe_default_timeout_confirmation', 'change_timeout_message', 10, 3 );
function change_timeout_message( $timeout_confirmation, $form, $feed ) {
    $timeout_confirmation['message'] = 'A fizetésed még feldolgozás alatt van. Hamarosan e-mailben értesítünk.';
    return $timeout_confirmation;
}
```

## `gform_stripe_webhook`: egyedi művelet a Stripe-eseményekre

A szűrő akkor fut, amikor a Stripe webhookon eseményt küld. Vele egyedi műveletet végezhetsz, vagy a bővítmény által alapból nem kezelt eseménytípust is feldolgozhatsz. A bővítmény alapból ezeket az eseményeket dolgozza fel:

| Eseménytípus |
|---|
| `charge.captured` |
| `charge.expired` |
| `charge.failed` |
| `charge.refunded` |
| `charge.succeeded` |
| `checkout.session.completed` |
| `checkout.session.async_payment_succeeded` |
| `checkout.session.async_payment_failed` |
| `customer.subscription.deleted` |
| `customer.subscription.updated` |
| `invoice.payment_succeeded` |
| `invoice.payment_failed` |
| `payment_intent.succeeded` |
| `payment_intent.payment_failed` |
| `setup_intent.succeeded` |
| `setup_intent.setup_failed` |

A Stripe-nak ennél több eseménytípusa van; a teljes lista a Stripe API-referenciájában található.

> **Megjegyzés**
>
> Az alapból kezelt eseményekhez a legtöbbször nem ezt a szűrőt érdemes használni, hanem a Gravity Forms fizetési horgait. Ha a régi elemek támogatása megszűnik, a szükséges események listája is rövidülhet.

| Horog | Mikor fut |
|---|---|
| `gform_post_payment_completed` | a fizetés teljesülése után |
| `gform_post_payment_refunded` | a fizetés visszatérítése után |
| `gform_post_payment_transaction` | miután egy fizetési tranzakció bekerült a bejegyzésbe |
| `gform_post_subscription_started` | az előfizetés sikeres létrehozása után |
| `gform_subscription_canceled` | az előfizetés lemondása után |
| `gform_post_add_subscription_payment` | egy előfizetéses (ismétlődő) fizetés teljesülése után |
| `gform_post_fail_subscription_payment` | egy előfizetéses fizetés sikertelensége után |
| `gform_post_payment_action` | bármilyen fizetéssel vagy előfizetéssel kapcsolatos művelet után |

```php
add_filter( 'gform_stripe_webhook', 'your_function_name', 10, 2 );
```

| Paraméter | Típus | Jelentés |
|---|---|---|
| `$action` | array | Az esemény adatait tartalmazó asszociatív tömb; nem támogatott eseménytípusnál üres tömb. |
| `$event` | `\Stripe\Event` | A webhookról érkezett Stripe-eseményobjektum. |

Az `$action` tömb kulcsai: `type`, `amount`, `transaction_type`, `transaction_id`, `subscription_id`, `entry_id`, `payment_status`, `note`.

Példa: a `charge.failed` esemény feldolgozása sikertelen fizetésként:

```php
add_filter( 'gform_stripe_webhook', 'stripe_webhook_custom_action', 10, 2 );
function stripe_webhook_custom_action( $action, $event ) {
    $type = rgar( $event, 'type' );

    switch ( $type ) {
        case 'charge.failed':
            $action['transaction_id'] = rgars( $event, 'data/object/id' );
            $entry_id                 = gf_stripe()->get_entry_by_transaction_id( $action['transaction_id'] );
            if ( ! $entry_id ) {
                return new WP_Error( 'entry_not_found', sprintf( 'Entry for transaction id: %s was not found. Webhook cannot be processed.', $action['transaction_id'] ) );
            }

            $entry = GFAPI::get_entry( $entry_id );

            $action['entry_id'] = $entry_id;
            $action['type']     = 'fail_payment';
            $action['amount']   = gf_stripe()->get_amount_import( rgars( $event, 'data/object/amount' ), $entry['currency'] );
            break;
    }

    return $action;
}
```

## `gform_stripe_webhook_signing_secret`: az aláírási titok módosítása

A szűrő az adott API-módhoz tartozó webhook-aláírási titkot (signing secret) módosítja. A beérkező webhookok érvényességét a bővítmény ezzel a titokkal ellenőrzi.

```php
add_filter( 'gform_stripe_webhook_signing_secret', 'your_function_name', 10, 3 );
```

| Paraméter | Típus | Jelentés |
|---|---|---|
| `$signing_secret` | string | A beérkező webhookok ellenőrzéséhez használt aláírási titok. |
| `$mode` | string | Az API módja: `live` vagy `test`. |
| `$gfstripe` | object | A `GFStripe` osztály példánya. |

Példa (a titkok helyére a saját értékeidet írd):

```php
add_filter( 'gform_stripe_webhook_signing_secret', 'change_secret', 10, 3 );
function change_secret( $signing_secret, $mode, $gfstripe ) {
    if ( $mode == 'test' ) {
        return 'whsec_teszt_titok';
    }
    return 'whsec_eles_titok';
}
```
