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.
|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.|
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 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.
Fortumo will respond with one of the following HTTP codes to indicate that your request has been received.
|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|
|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.
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.
|Subject||C=EE, ST=Tartumaa, L=Tartu, O=Fortumo Ltd., CN=api.fortumo.io|
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.