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.

Dictionary

Merchant Integrator of the Payments API.
Consumer Merchant's end-user who is making payments.
MSISDN Mobile Station International Subscriber Directory Number
Remote API API that is hosted by Fortumo against which merchant is making requests and that provides access to the payment infrastructure.
Local API API that is hosted by merchant against which Fortumo is making callback requests.
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.

REST

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.

Synchronicity

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 the merchant by making callback requests to the merchant hosted Local API. On object status change, a new callback request is made to the Local API.

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

Idempotency

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.

Versioning

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.

Security

Payments API is using full certificate based authentication. As the whole communication between your servers and Fortumo is encrypted with SSL/TLS, you will need to make sure certificates are attached to every incoming and outgoing request. All requests have to be made using a certificate from Fortumo approved Certificate Authorities. At the same time it is expected that you will carry out full certificate chain validation for Fortumo server certificates. In order to get your certificates whitelisted you will need to provide Fortumo the full CN in the certificate. Additional username/password validations are not supported.

Fortumo certificate validation
Subject C=EE, ST=Tartumaa, L=Tartu, O=Fortumo Ltd., CN=api.fortumo.io

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 is made to Local API provided by the merchant at each update to the REST object. Each callback will have a reference to the original request and the latest state of the object.

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