Ticketing and payment hooks

These hooks follow the paid side of HappenBoard Pro: ticket types, Stripe and WooCommerce orders, and refunds. They also cover paid lines that found no seat, the limit on paid checkouts and the card hold on booking requests. Use them to copy sales and refunds into your accounting, CRM or other tools.

The site owner’s side is in Setting up Stripe and Refunding an order. WooCommerce sales are covered in Selling tickets through WooCommerce. If you are new to HappenBoard hooks, start with Extending HappenBoard with hooks.

Every hook on this page is fired by HappenBoard Pro. See What Pro adds.

How an order is recorded

When a payment is confirmed, Pro writes one attendee row per ticket line, with a sale row beside it. The sale row keeps what the line was charged, what has been refunded of it and whether its seats count against the ticket’s capacity. The Orders dashboard reads these amounts, so a later price change does not rewrite past orders.

Amounts are in minor units of the currency: cents for EUR, yen for JPY. A checkout is paid in one currency. A cart that mixes currencies is refused before Stripe is called, and nothing on this page fires.

A cart of free tickets from the Ticket Picker block never reaches Stripe. Its tickets are issued at once, and only happenboard_rsvp_submitted fires, with source set to free_ticket. See Attendees and sign-up hooks.

Which hook fires when

A Stripe refund can come from the Orders screen or from the Stripe dashboard: both are recorded the same way, and only once. Each attendee cancelled along the way also fires happenboard_rsvp_cancelled.

Booking payments

Pro takes appointment payments by answering the free plugin’s booking payment filters, described in Appointment booking hooks. Its only hook of its own for them is happenboard_pro_booking_hold_hours, at the end of this page. Booking payments never fire the Stripe hooks above.

do_action( 'happenboard_pro_ticket_saved', int $ticket_id )

add_action(
    'happenboard_pro_ticket_saved',
    function ( $ticket_id ) {
        $tickets = new \HappenBoard\Pro\Service\Tickets\Repository();
        $ticket  = $tickets->find( (int) $ticket_id );
        if ( null === $ticket ) {
            return;
        }
        // $ticket['eventId'], $ticket['priceCents'], $ticket['currency']...
        my_crm_sync_ticket( $ticket );
    }
);

do_action( 'happenboard_pro_ticket_deleted', int $ticket_id, array<string,mixed>|null $snapshot )

add_action(
    'happenboard_pro_ticket_deleted',
    function ( $ticket_id, $snapshot ) {
        if ( ! is_array( $snapshot ) ) {
            return;
        }
        // The row as it was just before the delete.
        error_log( sprintf(
            'Ticket %d (%s) removed from event %d, %d sold.',
            $ticket_id,
            $snapshot['name'],
            $snapshot['eventId'],
            $snapshot['sold']
        ) );
    },
    10,
    2
);

apply_filters( 'happenboard_pro_checkout_limits', array $limits, string $ip )

add_filter(
    'happenboard_pro_checkout_limits',
    function ( $limits, $ip ) {
        // The box office computer sells many tickets an hour.
        if ( '203.0.113.10' === $ip ) {
            $limits['checkouts_per_hour'] = 200;
            $limits['seats_per_hour']     = 1000;
        }

        return $limits;
    },
    10,
    2
);

do_action( 'happenboard_stripe_checkout_completed', int $event_id, array<int,int> $created_attendee_ids, array<string,mixed> $session )

add_action(
    'happenboard_stripe_checkout_completed',
    function ( $event_id, $attendee_ids, $session ) {
        $session_id = (string) ( $session['id'] ?? '' );
        if ( '' === $session_id || get_option( 'my_sale_' . $session_id ) ) {
            return; // Already recorded by an earlier delivery.
        }
        my_accounting_record_sale(
            (int) $event_id,
            $attendee_ids,
            (int) ( $session['amount_total'] ?? 0 ),
            strtoupper( (string) ( $session['currency'] ?? '' ) )
        );
        update_option( 'my_sale_' . $session_id, 1, false );
    },
    10,
    3
);

do_action( 'happenboard_pro_ticket_unseated', int $attendee_id, array<string,mixed> $context )

add_action(
    'happenboard_pro_ticket_unseated',
    function ( $attendee_id, $context ) {
        if ( 'refunded' === $context['outcome'] ) {
            return; // Stripe already gave the money back.
        }
        wp_mail(
            get_option( 'admin_email' ),
            'Paid ticket without a seat',
            sprintf(
                'Attendee #%d (%s) paid for %d seat(s) of ticket %d and got none. Outcome: %s.',
                $attendee_id,
                $context['email'],
                $context['quantity'],
                $context['ticket_id'],
                $context['outcome']
            )
        );
    },
    10,
    2
);

do_action( 'happenboard_pro_stripe_refund_recorded', string $payment_intent, array<int,int> $gained, string $currency )

add_action(
    'happenboard_pro_stripe_refund_recorded',
    function ( $payment_intent, $gained, $currency ) {
        // One accounting line per attendee the refund reached.
        foreach ( $gained as $attendee_id => $minor_units ) {
            my_accounting_record_refund(
                $payment_intent,
                (int) $attendee_id,
                (int) $minor_units,
                $currency
            );
        }
    },
    10,
    3
);

do_action( 'happenboard_stripe_refunded', string $payment_intent, array<int,int> $cancelled, array<string,mixed> $source )

add_action(
    'happenboard_stripe_refunded',
    function ( $payment_intent, $cancelled, $source ) {
        // The whole payment is refunded: close the sale.
        my_accounting_close_sale(
            $payment_intent,
            (int) ( $source['amount_refunded'] ?? 0 ),
            strtoupper( (string) ( $source['currency'] ?? '' ) ),
            $cancelled
        );
    },
    10,
    3
);

apply_filters( 'happenboard_pro_wc_pay_later_methods', array<int,string> $methods, WC_Order $order )

add_filter(
    'happenboard_pro_wc_pay_later_methods',
    function ( $methods, $order ) {
        // This gateway puts orders in "processing" before any money is in.
        $methods[] = 'my_pay_on_site';

        return $methods;
    },
    10,
    2
);

do_action( 'happenboard_pro_wc_order_fulfilled', int $order_id, array<int,int> $created, WC_Order $order )

add_action(
    'happenboard_pro_wc_order_fulfilled',
    function ( $order_id, $created, $order ) {
        if ( array() === $created ) {
            return; // No ticket lines on this order.
        }
        $order->add_order_note( sprintf(
            '%d HappenBoard attendee row(s) created.',
            count( $created )
        ) );
        $order->save();
    },
    10,
    3
);

do_action( 'happenboard_pro_wc_order_refunded', int $order_id, array<int,int> $gained, string $currency )

add_action(
    'happenboard_pro_wc_order_refunded',
    function ( $order_id, $gained, $currency ) {
        // Only the amount new since the last call.
        foreach ( $gained as $attendee_id => $minor_units ) {
            my_accounting_record_refund(
                'wc_' . (int) $order_id,
                (int) $attendee_id,
                (int) $minor_units,
                $currency
            );
        }
    },
    10,
    3
);

do_action( 'happenboard_pro_wc_order_reversed', int $order_id, array<int,int> $cancelled, WC_Order $order )

add_action(
    'happenboard_pro_wc_order_reversed',
    function ( $order_id, $cancelled, $order ) {
        // Undo what you did when the order was fulfilled.
        foreach ( $cancelled as $attendee_id ) {
            my_crm_mark_cancelled( (int) $attendee_id, (int) $order_id );
        }
    },
    10,
    3
);

apply_filters( 'happenboard_pro_booking_hold_hours', int $hours )

add_filter(
    'happenboard_pro_booking_hold_hours',
    function ( $hours ) {
        // Decline unanswered requests after four days instead of six.
        return 96;
    }
);

Next steps

• Refunding an order: how full and partial refunds are made from the Orders screen.
• Attendees and sign-up hooks: the registration and cancellation hooks these payments trigger.
• Appointment booking hooks: booking prices and payments.