Skip to main content

Payment Intent Overview

The Payment Intent in Modem Pay’s H2H integration is a structured request representing an intention to process a payment. It allows partners to define the payment details, associated metadata, and optional direct charge information. Payment Intents provide flexibility for both regular payment flows and direct charges when specific account information is available.

Creating a Payment Intent​

When creating a Payment Intent, you provide a HostIntent object with the following key fields:

  • amount and currency – The payment amount and currency (currently "GMD").
  • network and account_number – Optional. If both are provided, Modem Pay will attempt to initiate a direct charge on the specified account using the chosen mobile money network ("wave" | "afrimoney" | "qmoney").
  • metadata – Optional key-value pairs for additional contextual data.
  • callback_url, return_url, cancel_url – Optional URLs for notifications or redirection after payment processing.
  • external_reference – Optional reference from the partner system to track the transaction.

Note: Providing both network and account_number triggers Modem Pay to attempt a direct charge. If omitted, the intent behaves as a standard payment request that can be completed via hosted checkout or API-driven payment methods.

Payment Intent Response​

Note: This is only returned when not a direct charge.

Once a Payment Intent is created, Modem Pay returns a PaymentIntent object. Key fields include:

  • id – Unique identifier for the payment intent.
  • amount and currency – Reflects the requested amount and currency.
  • is_session – Indicates whether the intent requires a hosted session to complete payment.
  • transactionId – Populated if a direct charge is successfully initiated.
  • callback_url – Returns the URL provided in the request for asynchronous updates.
  • business_id and account_id – Confirm the associated partner account.
  • type_of_payment – "regular" or "direct" to distinguish the flow used.
  • account_number and network – Included if a direct charge was attempted.
  • usd_fx_rate – Optional exchange rate information if the transaction involves currency conversion.
  • metadata and payment_metadata – Any partner-provided or system-generated contextual information.

Additional fields such as payment_link_id, pin, customer_name, and transaction_fee provide extra details depending on the payment flow and partner integration.

Flow Summary​

  1. Partner creates a HostIntent via the H2H endpoint.
  2. Modem Pay validates the intent and the partner’s authorization.
  3. If network and account_number are provided, Modem Pay attempts a direct mobile money charge.
  4. If not, a standard payment session is created and the returned PaymentIntent provides the details needed to complete the transaction.
  5. Updates and final results are communicated via the provided callback_url.

This design ensures partners can programmatically manage payments while retaining control over direct charges and metadata, with all sensitive operations secured and scoped to authorized business accounts.