| @@ -624,8 +624,24 @@ | ||
| 624 | 624 | $subscription_db_id, |
| 625 | 625 | gmdate( 'Y-m-d H:i:s', $canceled_at ) |
| 626 | 626 | ) |
| 627 | 627 | ); |
| 628 | + | |
| 629 | + // Notify consumers that the subscription has reached a terminal canceled state. | |
| 630 | + $canceled_record = Payments::get( $subscription_db_id ); | |
| 631 | + if ( is_array( $canceled_record ) ) { | |
| 632 | + /** | |
| 633 | + * Fires when a subscription reaches its terminal `canceled` state (for | |
| 634 | + * Stripe, after the billing period ends — `customer.subscription.deleted`). | |
| 635 | + * | |
| 636 | + * @param array<string, mixed> $subscription_record The canceled subscription payment record. | |
| 637 | + * @param array<string, mixed> $context Resolved context: form_id, entry_id, | |
| 638 | + * user_id (0 for guests), customer_email, | |
| 639 | + * type, gateway, mode. | |
| 640 | + * @since 2.12.0 | |
| 641 | + */ | |
| 642 | + do_action( 'srfm_subscription_canceled', $canceled_record, Payment_Helper::build_payment_context( $canceled_record ) ); | |
| 643 | + } | |
| 628 | 644 | } |
| 629 | 645 | |
| 630 | 646 | /** |
| 631 | 647 | * Update refund data for a payment. |
| @@ -767,8 +783,26 @@ | ||
| 767 | 783 | $currency |
| 768 | 784 | ) |
| 769 | 785 | ); |
| 770 | 786 | |
| 787 | + // Notify consumers that a refund was recorded against this payment. | |
| 788 | + $is_full_refund = $total_after_refund >= $original_amount; | |
| 789 | + $refunded_payment = Payments::get( $payment_id ); | |
| 790 | + $refunded_payment = is_array( $refunded_payment ) ? $refunded_payment : $payment; | |
| 791 | + /** | |
| 792 | + * Fires when a refund is recorded against a SureForms payment (covers both | |
| 793 | + * the Stripe webhook and admin-initiated refund paths). | |
| 794 | + * | |
| 795 | + * @param array<string, mixed> $payment Payment record (a `sureforms_payments` row). | |
| 796 | + * @param float $refund_amount Refunded amount for this event, in the store's decimal currency. | |
| 797 | + * @param bool $is_full_refund Whether the cumulative refunds now cover the full payment. | |
| 798 | + * @param array<string, mixed> $context Resolved context: form_id, entry_id, | |
| 799 | + * user_id (0 for guests), customer_email, | |
| 800 | + * type, gateway, mode. | |
| 801 | + * @since 2.12.0 | |
| 802 | + */ | |
| 803 | + do_action( 'srfm_payment_refunded', $refunded_payment, (float) $new_refund_amount, $is_full_refund, Payment_Helper::build_payment_context( $refunded_payment ) ); | |
| 804 | + | |
| 771 | 805 | return true; |
| 772 | 806 | } |
| 773 | 807 | |
| 774 | 808 | /** |
| @@ -1068,8 +1102,24 @@ | ||
| 1068 | 1102 | if ( false === $result ) { |
| 1069 | 1103 | Helper::srfm_log( 'Failed to update subscription record for initial payment. Subscription ID: ' . $subscription_id . '.' ); |
| 1070 | 1104 | } else { |
| 1071 | 1105 | Helper::srfm_log( 'Initial subscription payment processed successfully. Subscription ID: ' . $subscription_id . '.' ); |
| 1106 | + | |
| 1107 | + // Notify consumers that the initial subscription charge succeeded. | |
| 1108 | + $payment = Payments::get( $subscription_id ); | |
| 1109 | + if ( is_array( $payment ) ) { | |
| 1110 | + /** | |
| 1111 | + * Fires when a SureForms payment reaches the `succeeded` state — a | |
| 1112 | + * one-time payment, or the initial charge of a subscription. | |
| 1113 | + * | |
| 1114 | + * @param array<string, mixed> $payment Payment record (a `sureforms_payments` row). | |
| 1115 | + * @param array<string, mixed> $context Resolved context: form_id, entry_id, | |
| 1116 | + * user_id (0 for guests), customer_email, | |
| 1117 | + * type, gateway, mode. | |
| 1118 | + * @since 2.12.0 | |
| 1119 | + */ | |
| 1120 | + do_action( 'srfm_payment_completed', $payment, Payment_Helper::build_payment_context( $payment ) ); | |
| 1121 | + } | |
| 1072 | 1122 | } |
| 1073 | 1123 | } |
| 1074 | 1124 | |
| 1075 | 1125 | /** |
| @@ -1173,8 +1223,25 @@ | ||
| 1173 | 1223 | // Send payment data to middleware for analytics. |
| 1174 | 1224 | if ( ! empty( $charge_id ) ) { |
| 1175 | 1225 | $get_secret_key = Stripe_Helper::get_stripe_secret_key( $this->mode ); |
| 1176 | 1226 | Stripe_Helper::intersect_payment( $charge_id, $get_secret_key, '', 'SureForms' ); |
| 1227 | + } | |
| 1228 | + | |
| 1229 | + // Notify consumers that a subscription renewal charge succeeded. | |
| 1230 | + $renewal_payment = Payments::get( $payment_entry_id ); | |
| 1231 | + if ( is_array( $renewal_payment ) ) { | |
| 1232 | + /** | |
| 1233 | + * Fires when a subscription renewal charge succeeds and its payment | |
| 1234 | + * row has been recorded. | |
| 1235 | + * | |
| 1236 | + * @param array<string, mixed> $payment Renewal payment record (a `sureforms_payments` row). | |
| 1237 | + * @param array<string, mixed> $parent_subscription The parent subscription payment record. | |
| 1238 | + * @param array<string, mixed> $context Resolved context: form_id, entry_id, | |
| 1239 | + * user_id (0 for guests), customer_email, | |
| 1240 | + * type, gateway, mode. | |
| 1241 | + * @since 2.12.0 | |
| 1242 | + */ | |
| 1243 | + do_action( 'srfm_subscription_renewed', $renewal_payment, $subscription_record, Payment_Helper::build_payment_context( $renewal_payment ) ); | |
| 1177 | 1244 | } |
| 1178 | 1245 | } else { |
| 1179 | 1246 | Helper::srfm_log( 'Failed to create renewal payment record.' ); |
| 1180 | 1247 | } |
