fluentcart-payment-gateways

FluentCart payment gateways

Implement a gateway as a provider adapter around FluentCart's order, transaction, and subscription state machine. A successful browser callback is not proof of settlement.

Read gateway-contract.md before creating the PHP class, checkout JavaScript, webhook, or subscription branch.

Implement the required contract

Extend AbstractPaymentGateway and supply BaseGatewaySettings. Implement:

• meta()
• fields()
• makePaymentFromPaymentInstance()
• handleIPN()
• getOrderInfo()

GatewayManager 1.6.0 requires meta keys brand_color, description, icon, logo, route, status, and title. Also provide slug, upcoming, label/admin_title where the corresponding UI path reads them. Keep route, slug, registration key, frontend event suffix, stored option key, and webhook method consistent.

Attach the listener by fluentcart_loaded at the latest, then register during fluent_cart/register_payment_methods. In 1.6.0 the registration action runs in an earlier init callback than fluent_cart/init; adding this listener from fluent_cart/init is too late.

add_action('fluent_cart/register_payment_methods', static function (): void {
    fluent_cart_api()->registerCustomPaymentMethod(
        'acme_pay',
        new \Acme\FluentCart\AcmeGateway()
    );
});

registerCustomPaymentMethod requires an AbstractPaymentGateway instance. GatewayManager invokes boot() when present and injects StoreSettings.

Process the initial payment

Use the supplied PaymentInstance. Resolve/create provider objects with a stable idempotency key derived from the FluentCart transaction/payment attempt and mode. Return the response shape used by the active checkout client; 1.6.0 built-ins use status plus redirect_to or redirect_url depending on path, so test the concrete checkout script instead of copying the generic docs example.

Never:

• create a second FluentCart order for the same PaymentInstance;
• trust client amount/currency/customer/provider IDs;
• mark an order paid before provider verification;
• store raw card data or secret credentials in order/transaction meta;
• turn a free trial into an unsupported zero-amount charge.