Paiements

The Collect Payment screen asks your payment provider (Paystack, Hubtel, Flutterwave, MTN MoMo or any other with a web API) to charge the caller, then ends the USSD session with a message. The caller approves the payment on the mobile money prompt that their network sends next.

1. The caller reaches Collect Payment

   Usually after a question that saved the amount, such as amount.

2. Asterisks asks your provider to charge them

   It sends the request you set up, using your provider account and API key.

3. The session ends with your message

   Approve the GHS 20.00 payment on the prompt that follows. Thank you!

4. The caller approves on their phone

   Their network shows its own PIN prompt. Your provider then reports the result.

1. Collect the amount first

   Add an Ask a Question screen with Answer type Amount and Save the answer as amount. Skip this if the price is fixed.

2. Add Collect Payment

   Click Collect Payment in the toolbox (under Actions) and connect the question to it.

3. Write the closing message

   In What the phone shows, tell the caller what happens next. If you leave it empty they see "Please check your phone to authorize the payment."

4. Fill in the Payment section

   Use the values from your provider's API documentation:

   Setting	What to enter
   Payment provider	Your provider, or Custom for any other.
   API URL	The provider’s “charge” or “request payment” address.
   API key	Your provider's secret key. It is sent as Authorization: Bearer <key>.
   HTTP method	Almost always POST.
   Request body	The JSON your provider expects. Put the amount, currency and phone number here, using saved answers like {{amount}} and {{MobileNumber}}.
   Headers	Any extra headers your provider asks for.

5. Save and test with test keys

   Use your provider's test (sandbox) key first and run the flow from a real phone. Switch to your live key once a test payment goes through.

A typical mobile money request body. Field names differ by provider, so copy the shape from your provider's documentation:

{
  "amount": "{{amount}}",
  "currency": "GHS",
  "phone": "{{MobileNumber}}",
  "reference": "{{SessionId}}",
  "callback_url": "https://apis.useasterisks.com/api/ussd/webhooks/payment/{{ProjectId}}/{{SessionId}}"
}

• {{SessionId}} as the reference lets you match the payment to the USSD session later.
• Some providers want the amount in the smallest unit (pesewas), so 20 cedis is 2000. Check your provider's documentation.

If your provider can send a notification to a web address when a payment finishes, point it at your Asterisks payment address. Asterisks then records the result against the session:

https://apis.useasterisks.com/api/ussd/webhooks/payment/{{ProjectId}}/{{SessionId}}

Put it in the request body (as above) when your provider accepts a per-payment notification address. Asterisks reads the status from data.status, Data.Status or status in the notification:

Delivering what the caller paid for

The USSD session has already ended by the time the payment completes, so the caller won't see another screen. To deliver the goods (send a receipt SMS, credit an account), have your provider notify your own systemas well, and act on its confirmation there. Never deliver on the USSD request alone, before the provider confirms.

Your provider must answer within 2 seconds. If it refuses the request, the caller sees "Payment could not be initiated. Please try again later." If it is too slow or can't be reached, they see "An error occurred while processing payment. Please try again." Either way the session ends.

• Double-check the API URL and API key (test keys only work with test addresses, and live keys with live ones).
• Check the body is valid JSON: every quote and comma in place.
• Make sure the amount is in the format your provider expects.