The contract
These two filters are how MAM Suite talks to payment processors. mam-woocommerce fires mam_pmt_charge_card during checkout and settling; the refund/cancellation flows (in MAM WooCommerce Product Vendors) fire mam_pmt_refund_card. A payment plugin — MAM Stripe Manager, MAM Poynt, MAM WooCommerce PayPal — answers them: it checks payment_method, and either processes the request and adds result keys, or returns the array unchanged so another handler can claim it.
mam_pmt_charge_card
$result = apply_filters( 'mam_pmt_charge_card', array $args );Argument keys mam-woocommerce sends:
| Key | Type | Description |
|---|---|---|
customer_id |
int |
WordPress user to charge (their stored payment method is used). |
amount |
float |
Amount to charge. With Place Hold on Order = Yes, this is 120% of the order total for the initial hold. |
post_id |
int |
The WooCommerce order id. |
payment_method |
string |
Gateway slug, default 'stripe' (filterable via mam_payment_method). Handlers must pass through requests for other gateways. |
capture |
string |
'no' = place an authorization hold; 'yes' (or absent) = capture. |
last_charge_id |
string |
(settle path) The open hold to capture instead of creating a new charge. |
settle_order |
bool |
Whether the charge should settle on the order (from mam_payment_settle_on_order). |
statement_descriptor |
string |
Optional card-statement text (from the statement_descriptor option). |
Returns the array with at least status (truthy on success, false on failure) and charge (the gateway charge object, or null). mam-woocommerce treats an empty/false status as a failed payment: the order moves to Failed and the app gets a charge-failure message.
mam_pmt_refund_card
$result = apply_filters( 'mam_pmt_refund_card', array $args );Argument keys as fired by the suite’s refund flows:
| Key | Type | Description |
|---|---|---|
customer_id |
int |
The order’s customer. |
amount |
float |
Amount to refund — the full order total, or the partial-cancel amount. |
transaction_id |
string |
The gateway charge/transaction id to refund against. |
post_id |
int |
The WooCommerce order id. |
Returns the array with the gateway’s refund result; the caller stores it on the order (refund_results meta).
Example — implement a custom gateway
add_filter( 'mam_pmt_charge_card', function ( $args ) {
if ( ! is_array( $args ) || ( $args['payment_method'] ?? '' ) !== 'mygateway' ) {
return $args; // not ours — pass through untouched
}
$ok = MyGateway::charge( $args['customer_id'], $args['amount'], [
'hold' => ( $args['capture'] ?? 'yes' ) === 'no',
'reference' => 'wp_order_' . $args['post_id'],
] );
$args['status'] = (bool) $ok;
$args['charge'] = $ok ?: null;
return $args;
} );Notes
- Idempotency is the handler’s job. The Stripe implementation short-circuits duplicate submissions (re-uses an existing succeeded/held intent for the same amount) and enforces a charge-amount ceiling of order total × 1.2 (filterable via
mam_pmt_charge_amount_tolerance). Custom handlers should do the same. - A handler must never assume it is the only one registered — always gate on
payment_method. - Free orders skip the charge filter entirely.
Related articles
- Hook:
mam_wc_settle_order - Recipe: Configure checkout for the app
Metadata
| Field | Value |
|---|---|
| Article type | Hook Reference |
| Plugin slug | mam-woocommerce (fires charge); implemented by payment plugins |
| Applies to plugin version | 26.19.3+ |
| Category | Extending MAM Suite |
| Hook type | filter (both) |
| Audience | PHP developer / payment-plugin author |
| Last verified | 2026-06-10 |
