Payment Intent Overview

Every payment in the H2H API starts with a payment intent. You create one by calling the same endpoint every time. What happens next depends on what you send.

One endpoint, two modes

Mode	When	What you get back	What to do next
Direct charge	You send network + account_number	A charge response with next_step	Follow the Direct Charge guide
Standard	You leave out network and account_number	A PaymentIntent object	Complete the payment via hosted checkout or your chosen payment method

The rule is simple: sending both network and account_number triggers a direct charge. If either is missing, you get a standard payment intent.

Most H2H partners use direct charge. Use standard mode when you do not know the customer's mobile money details yet, or when you want the customer to choose how to pay.

Creating a payment intent

curl -X POST "https://api.modempay.com/h2h/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "amount": 10,
      "currency": "GMD",
      "network": "afrimoney",
      "account_number": "7012345",
      "external_reference": "order-1042",
      "metadata": { "customer_id": "cus_889" },
      "callback_url": "https://yourapp.com/payments/callback"
    }
  }'

Request fields

Field	Required	Meaning
amount	Yes	Amount to charge the customer
currency	Yes	Currently "GMD"
network	For direct charge	Mobile money network: "wave", "afrimoney", "qmoney", or "aps"
account_number	For direct charge	The customer's mobile money number, in local format
external_reference	No	Your own reference (order ID, invoice number). Use it to match Modem Pay payments to records in your system
metadata	No	Key-value pairs you want stored with the payment. Returned to you in responses and webhooks
callback_url	No	URL where Modem Pay sends the result of this payment
return_url	No	Where the customer is sent after completing payment (standard mode / hosted flows)
cancel_url	No	Where the customer is sent if they cancel (standard mode / hosted flows)

Tip: Always send external_reference. When you are reconciling payments later, it is much easier to search by your own order ID than by Modem Pay's IDs.

The response depends on the mode

Direct charge response

If you sent network and account_number, the response is a charge response with a transactionId and next_step telling you how to complete the payment. This is covered fully in the Direct Charge guide — read it before going live.

Standard response: the PaymentIntent object

If you did not trigger a direct charge, you get a PaymentIntent object.

The fields you will use:

Field	Meaning
id	Unique ID of the payment intent. Save it
amount, currency	Echo of what you requested
type_of_payment	"regular" or "direct" — which mode this intent used
is_session	true means the customer completes payment through a hosted session
callback_url	The URL you provided for result notifications
external_reference	Your reference, echoed back
metadata	Your key-value pairs, echoed back

Fields for your records:

Field	Meaning
business_id, account_id	The partner business and account this payment belongs to
transaction_fee	The fee applied to this payment
usd_fx_rate	Exchange rate, present when currency conversion is involved
payment_metadata	System-generated context about the payment
customer_name	Customer name, when available for the flow used
payment_link_id	Present when the intent came from a payment link

You do not need most of the record fields to complete a payment. They exist for reporting and reconciliation.

Flow summary

1. You create a payment intent (POST /h2h/v1/payments)
2. Modem Pay validates the request and your authorization
3. If network + account_number were sent → a direct mobile money charge starts. Follow Direct Charge
4. If not → you get a PaymentIntent. Complete it through the hosted session or your chosen method
5. The final result reaches you through your callback_url or webhooks

In both modes, the same rule from the Direct Charge guide applies: a payment is only successful when its status is completed.