Message delivery

When your service receives a message, Fortumo will make an HTTP GET request to the URL that you have specified in the service configuration (for example The content from the response that Fortumo receives from your URL (or actually the first 120 characters of it) is then sent back to the user as a reply message. The parameters of that HTTP GET request specify the senders phone number, message content etc. So you can use all that information to generate the reply message.

In case of user generated errors like mistyped message text, missing resource or any other situation, when service-provider is not able to provide the service, your back-end should response with a HTTP code 600 and an error description, eg:

Status: HTTP/1.1 600 user-error
Error: user not found. Please contact

Transaction will be marked as cancelled and when applicable, user will be billed with zero or lowest available tariff.

Premium SMS API flow

API Flow

Handling billing status

MO (Mobile Originating Billing) and MT (Mobile Terminating Billing) billing are the two methods how carriers charge users for Premium SMS transactions. In short, with MO-billing user is charged for sending the message and with MT-billing he is charged for receiving a reply message.

Countries which use MT-billing (e.g. UK) the billing reports are sent immediately as “ok” or “fail”.

Countries with MO-billing (like Vietnam) the billing reports are sent with a delay. Billing status is updated from Fortumo within 36 hours from state “pending” to “success” or to “failed”. So, in these countries you should provide the service not only if the billing status is “ok”, but also with status “pending”. Actually, in most cases “pending” status in MO countries already means the “ok” status (like in the current case, the customer did pay for the message).

Additional details on MO and MT billing statuses handling is available on dedicated Handling Billing Status page.

Handling billing status

Payment flow with MO billing

MO flow

Payment flow with MT billing

MT flow

Sample payment

  • Mobile device sends SMS with text: KEYWORD1 KEYWORD2 BODYTEXT to shortcode 17163, where:

    keyword1 is correlated with price point (TXT05 = 0.5€ in Finland); keyword2 shows service (your service keyword, which you declared creating the API Service); bodytext can be any content – custom parameter, user identifier, etc; shortcode is country specific Premium SMS number, shows price point (17163 = 0.5€ in Finland).

For example “TXT05 MY_API_SERVICE user12” to 17163. So you will know that user12, which in your system is John Smith sends SMS with Finnish SIM card, transaction worth 0.5€.

  • SMS is sent to Fortumo server
  • Fortumo server makes HTTP request to your back end URL
  • Your back end URL hosts payment processor code (sample.php) and sends response as text message
  • Response is sent to the mobile device as text message

For example “Thank you user12 for sending MY_API_SERVICE to TXT05.”. You can forward any information that is needed for service. Please note that only first 120 characters will arrive to end-user.

Help us improve our Merchants Portal. Was this article helpful?