Payments API

Payments API is a direct carrier billing API that connects the world's leading digital content merchants, app stores and device manufacturers to mobile operators. Payments API is designed to provide you a possibility offer server to server payments using Fortumo infrastructure and carrier billing connectivity. This API is built to provide high availability and high scale payment processing.

Payments API is an on-demand payment product. In order to gain access to the product, please contact your account manager. If you are a new merchant, please get in touch with our business development team.


Merchant Integrator of the Payments API.
Consumer Merchant's end-user who is making payments.
MSISDN Mobile Station International Subscriber Directory Number
Authorisation Consumer authorisation for the merchant for making payments on behalf of the consumer.
Payment Ongoing or finished monetary transaction.
Payment channel A specific provider of a payment method, mobile network operator.
Capability Describes the methods of authorisation and charging supported for a payment channel.


Payments API is designed according to the REST principles where different resources are created and updated. This allows easy integration using existing tools and provides established security infrastructure between the parties. This also simplifies the overall design and implementation of the API functionalities.


Payments API is designed to be fully asynchronous and the immediate response indicates only if the initial submission of the API call has succeeded (e.g. contains valid request body that can be parsed). Actual results of the methods are delivered to you via callbacks. On object status change, a new callback request is made to your endpoint.

HTTP response codes

Fortumo will respond with one of the following HTTP codes to indicate that your request has been received.

Code Description
200 Everything OK, request queued for processing
400 Bad request containing errors in the message (e.g. mandatory field missing, PIN/MSISDN too short,)
403 Certificate is valid but merchant is not supported.
406 Content-Type was not application/json
495 Certificate missing
500 Service unavailable due to a temporary overloading or maintenance. Retry required


All method calls with exactly the same input parameters always result in the same behaviour. This consistent behaviour helps to avoid duplications in case of failures and retries. For example, in case of a time-out error it is safe to retry sending the same API charge calls multiple times. When the call successfully delivers its message, the action is executed only once, and the payment would not be duplicated. Although multiple refunds are allowed, the amount of refund cannot exceed the original amount charged.


Payments API is versioned and versions are defined for actual endpoints and flows. For example it would be possible to use v1 of the authorisation flow and v3 of the payment flow. API version is bumped only when breaking changes are introduced in the interfaces. Version deprecation is communicated out 12 months before closing the operation.

Integration overview

Payments made using Fortumo Payments API consist of two steps: authorisation and charging. When a consumer has decided to make a purchase, you will first need to get their authorisation and retrieve a charging token that can be used for charging the consumer once or multiple times. Depending on payment channel there can be one or more authorisation flows to choose from. Information about which authorisation methods are available for a specific payment channel can be obtained via Capabilities API. After a successful authorisation, consumer can be charged any amount within consumer available limits indicated in the authorisation object.

As described above, Payments API is RESTful and asynchronous. At retrieving each request only HTTP 200 OK will be given in response and a separate callback will be sent to you at each update to the REST object. Each callback will have a reference to the original request and the latest state of the object.

Launching a Payments API integration typically includes the following steps:

  1. Sorting out integration Prerequisites - preparing API access keys and channel configuration
  2. Optionally implementing Capabilities method for dynamic route configuration
  3. Implementation of Authorisations methods and building the user experience for collecting end user consent and authorisation.
  4. Implementation of Payments methods based on your payment flow needs, e.g. one-time payment or recurring subscription
  5. Optionally implementing Refunds
  6. Testing the implementation using sandbox and live channels together with your Intergation Manager
  7. Carrying out additional User Acceptance Testing if required by the telcos and going live
Help us improve our Merchants Portal. Was this article helpful?