Payments

After receiving a verified charging token you can proceed with charging the Consumer by making a request towards Payments endpoint.

When dealing with subscriptions and a user has unsubscribed, then a new authorisation and charging token is required if the user subscribes again.

Payments request parameters

Parameter Type Required Description
item_description String Mandatory Item name. Attribute that specifies what is the service you are selling. Max length is 32 characters but should be kept as short as possible. Example: Premium access
amount Object Mandatory Contains attributes value and currency for specifying the price you want to charge for the service.
charging_token String Mandatory A valid and verified customer identifying token, provided by Authorisations API and issued by Fortumo. Example: 8923b690-2d70-4d51-8caa-d4ab2871f188:8fe403b3
merchant String Mandatory Your Fortumo account's merchant ID. Example: 93d9523134eee0f22716e49093af881a
operation_reference String Mandatory Operation reference. Attribute that allows you to specify a custom reference to every payment session initiated. It will be returned to you with Fortumo notifications so that you can map all payments internally. Operation_reference has to be unique for each payment session. Example: payment0001
callback String Mandatory Callback URL to be used for receiving payment callbacks. Example: https://www.example.com/payment
amount object parameters
Amount      
value Double Mandatory Price amount. Attribute that specifies how much you are going to charge the consumer for your service. Example: 4.99
currency String, ISO 4217 Mandatory Currency code. Attribute that specifies the currency in which you are about to charge the consumer. Example: EUR

Payments callback parameters

transaction_id String Mandatory Unique billing transaction id. Example:dc06a486787906f4b88dc74740f82c99
transaction_state String Mandatory Current state of the transaction. Example: pending_charge/charged
merchant String Mandatory Your Fortumo account's merchant ID. Example: 93d9523134eee0f22716e49093af881a
operation_reference String Mandatory Operation reference. Attribute that allows you to specify a custom reference to every payment session initiated. It will be returned to you with Fortumo notifications so that you can map all payments internally. Operation_reference has to be unique for each payment session. Example: payment0001
callback String Mandatory Callback URL to be used for receiving payment callbacks. Example: https://www.example.com/payment
consumer_identity String Mandatory A unique string that is generated for a single consumer. Example: 2b924672-f1a3-3d60-8173-e8a0a0b41e99
error Object Optional In case errors happen an errorcode and description is listed. Example: 602
timestamp Datetime Mandatory Timestamp of the sent callback. Example: 2016-08-22T09:25:54.394Z
price Object Mandatory Contains attributes amount and currency for specifying the price you want to charge for the service.
price object parameters
Price      
amount Double Mandatory Price amount. Attribute that specifies how much you are going to charge the consumer for your service. Example: 4.99
currency String, ISO 4217 Mandatory Currency code. Attribute that specifies the currency in which you are about to charge the consumer. Example: EUR

Request to Remote API - initiating a payment session

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /payments HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....CgVKRghGWI6-QjMv8JpJi1GarWaQ06CG9d0c1PDFek

{
    "item_description": "Premium Subscription",
    "amount": {
        "value": "2.50",
        "currency": "EUR"
    },
    "charging_token": "08356bca-e665-4446-b1c6-d2ba0258ab51:d767c48b",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "payment_1",
    "callback": "https://example.com/payments"
}

All price amounts must be specified as gross amount.

Callback to Local API

After initiating a payment session, first callback made to Local API indicates that payment processing has begun and charge confirmation is pending.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "transaction_id": "90ffc21b-8830-467d-b1c6-18e3661cc44a",
    "transaction_state": "pending_charge",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "payment_1",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "error": {},
    "timestamp": "2016-08-22T11:57:35.089Z",
    "price": {
        "amount": 2.5,
        "currency": "EUR"
    }
}

After carrier has confirmed that Consumer linked to specified charging token can indeed be charged, Fortumo calls your Local API and provides a final charged transaction_state.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "transaction_id": "90ffc21b-8830-467d-b1c6-18e3661cc44a",
    "transaction_state": "charged",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "payment_1",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "error": {},
    "timestamp": "2016-08-22T11:57:35.450Z",
    "price": {
        "amount": 2.5,
        "currency": "EUR"
    }
}

Charging errors

In case charging the Consumer fails, transaction_state failed is returned in callback to your Local API together with an error code and message that provide more information about the reason charging has failed.

Code Error message Description
ERR_400 Bad request  
ERR_401 Authentication failure  
ERR_403 Forbidden  
ERR_404 Not found  
ERR_409 Duplicate request  
ERR_500 Provider service was incapable of handling request  
ERR_503 Provider service unavailable  
ERR_700 Charging operation failed, retries not allowed (generic) General payment failure. Payment will not succeed upon retries.
ERR_701 Charging operation failed, retries are allowed Temporary payment failure. Payment may succeed upon retries.
ERR_702 Provider is busy Connection problem with the operator. Operator might be having a downtime.
ERR_703 Payment already in final state, modifications not allowed Payments API specific error. If new transaction is being attempted with an already existing operation reference. Operation reference parameter should be unique per each transaction.
ERR_710 Insufficient credit for user (Not enough funds) End-user does not have enough funds on balance.
ERR_715 User charge limit exceeded or purchase limit reached Spending limit for the specific MSISDN is reached. The limit is set on either Fortumo or operator side.
ERR_720 User is blacklisted or blocked (charging) End-user is blacklisted by either Fortumo or operator.
ERR_721 User account is not enabled End-user's SIM card is not enabled by the operator.
ERR_722 User account is disabled End-user's SIM card is disabled by the operator.
ERR_723 User not permitted to purchase this content type Some operators block specific content that Merchant might provide.
ERR_725 User is not supported by the operator End-user MSISDN belongs to a different operator.
ERR_730 Transaction not found  
ERR_735 Charging amount not supported Price amount is invalid. May be in a wrong format or exceeds the maximum price range that is set by the operator.
ERR_740 Currency not supported or invalid The currency attempted to charge with is not the default currency of the country. Each country have its default currency for charging.
ERR_750 Authorisation has failed Payments API specific error. When charge attempt is being made before authorisation has ended.

Charging limits

In order to mitigate the risk of fraudulent payment behaviour, it is possible to limit

  • the number of payments that can be processed by one consumer in given timeframe (day/week/month)
  • the amount of currency that can be spent by one consumer in given timeframe (day/week/month)

In case you are interested in having specific limits applied to your services, please contact your account manager.

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