Skip to main content

​
Payment Flow

  1. Build the payment data in your plugin.
  2. Pass the data to your adapter.
  3. Create the Monime checkout request.
  4. Redirect the user to Monime checkout.
  5. Handle the webhook response in your plugin.
The key benefit of this flow is that you do not need to replace your own business logic. Your plugin can keep its current order or record system and only delegate the payment step to Monime.

​
Example Adapter

use Monime\contracts\PaymentAdapterInterface;
use Monime\core\CreateDonationRequest;

class CustomMonimeAdapter implements PaymentAdapterInterface
{
    public function getAdapterId(): string
    {
        return 'custom_adapter';
    }

    public function buildPaymentPayload(array $data): CreateDonationRequest
    {
        return new CreateDonationRequest(
            items: $data['lineItems'],
            idempotency_key: $data['idempotency_key'],
            reference: $data['reference'],
            name: $data['name'],
            description: $data['description'],
            cancelurl: $data['cancel_url'],
            success_url: $data['success_url'],
            financialAccountId: $data['financialAccountId'] ?? '',
            currency: $data['currency'] ?? 'SLE',
            paymentOptions: $data['paymentOptions'] ?? [],
            metadata: $data['metadata'] ?? [],
            callbackState: $data['callbackState'] ?? ''
        );
    }
}
This example shows how your plugin should translate its own internal data into a Monime checkout request. In a real plugin, the $data array would usually come from your order builder, donation form, invoice screen, or membership checkout flow.

​
Webhook Handling

Use your webhook adapter to update custom orders, donations, invoices, or other payment records when Monime sends event updates. Monime verifies the webhook signature before it dispatches the payload to your adapter. That means handleWebhook() receives a verified payload, and your job is to map that payload back to your own record system. The interface you need to implement is: 
namespace Monime\core;

interface WebhookAdapterInterface
{
    /**
     * Handle a verified Monime webhook payload for the adapter's platform.
     */
    public function handleWebhook(array $payload): void;
}

​
Example Webhook Adapter

use Monime\contracts\PaymentAdapterInterface;
use Monime\core\CreateDonationRequest;
use Monime\core\WebhookAdapterInterface;

class CustomMonimeAdapter implements PaymentAdapterInterface, WebhookAdapterInterface
{
    public function getAdapterId(): string
    {
        return 'custom_adapter';
    }

    public function buildPaymentPayload(array $data): CreateDonationRequest
    {
        return new CreateDonationRequest(
            items: $data['lineItems'],
            idempotency_key: $data['idempotency_key'],
            reference: $data['reference'],
            name: $data['name'],
            description: $data['description'],
            cancelurl: $data['cancel_url'],
            success_url: $data['success_url'],
            financialAccountId: $data['financialAccountId'] ?? '',
            currency: $data['currency'] ?? 'SLE',
            paymentOptions: $data['paymentOptions'] ?? [],
            metadata: $data['metadata'] ?? [],
            callbackState: $data['callbackState'] ?? ''
        );
    }

    public function handleWebhook(array $payload): void
    {
        // Read the verified Monime payload here.
        // Match the payment reference back to your local record.
        // Update the order, donation, invoice, or membership status.
    }
}

​
What handleWebhook() Should Do

Your handleWebhook() method should usually:
  1. Find the internal record associated with the Monime reference.
  2. Confirm the payment state in the payload.
  3. Update your local record only if the event has not already been processed.
  4. Store any useful Monime identifiers for future support or reconciliation.
Common webhook actions include:
  • marking an order as paid,
  • recording the Monime transaction reference,
  • activating access to a service or membership,
  • and storing the final payment status for audit purposes.

​
Best Practices

  • Keep adapter logic small and predictable.
  • Do not hardcode sensitive credentials in your custom plugin.
  • Treat webhook delivery as the source of truth for payment completion.
  • Make webhook handlers idempotent so repeated deliveries do not create duplicate records.
  • Log the Monime reference and your internal reference together so you can trace payments later.