Refunds

Payments that Consumers need to be refunded for can be processed via Refunds API.

Endpoint to Refund API: https://api-jwt.fortumo.io

Refunds API is available for a limited number of carriers. Please confirm the availability of the API with your account manager.

Refund request parameters

Parameter Type Required Description
payment_operation_reference String Mandatory Operation reference of the original payment that you wish to refund. Example: payment0001
refund_reason String Mandatory Reason of the refund. Should contain the merchant name. Example: Customer's request
merchant String Mandatory Your merchant id. Example: 93d9523134eee0f22716e49093af881a
operation_reference String Mandatory Operation reference for the refund. Should be unique for each refund. Example: refund0001
callback String Mandatory Callback url where refund notifications will be sent. Example: https://www.example.com/payment

Refund callback parameters

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
payment_amount Object Mandatory Contains attributes value and currency for specifying the amount that will be refunded.
refund_status String Optional The current status of the refund flow. Example: refunded
channel Object Optional Contains attributes code and country for specifying the operator and its country.
transaction_id String Mandatory Unique billing transaction id. Example:dc06a486787906f4b88dc74740f82c99
consumer_identity String Mandatory A unique string that is generated for a single consumer. Sent with a callback to your server during MO flow. 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
Payment_amount object parameters
payment_amount      
value Double Mandatory Price amount. Attribute that specifies how much you are going to refund to the consumer. Example: 4.99
currency String, ISO 4217 Mandatory Currency code. Attribute that specifies the currency in which you are about to refund for the consumer. Example: EUR
Channel object parameters
Channel      
code string Mandatory Specifies the identification code of the carrier. Example: sandbox-ee
country String, ISO 3166-1 alpha-2 Mandatory Country code. Attribute that specifies the country of your consumer's carrier. Example: EE

Request to Remote API - initiating a refund

In order to initiate a refund, a POST request towards Fortumo Remote API must be made. While creating the refund object, you will specify the original payment that is about to be refunded and the reason why it needs to be refunded. Refunds also have their own unique operation reference just as all authorisations and payments.

1
2
3
4
5
6
7
8
9
10
POST /refunds HTTP/1.1
Content-Type: application/json

{
    "payment_operation_reference": "payment_1",
    "refund_reason": "API refund by MyCoolCompany",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "refund_1",
    "callback": "https://your-callback-url-here.com"
}
Callback to Local API

After the refund has been processed by Fortumo, your server will be sent a notification with the refund status. Possible refund statuses are new, pending, refunded, failed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "merchant": "d1ed37d8110076db78f06e13a6fc029a",
    "operation_reference": "refund_1",
    "payment_amount": {
        "value": 2.50,
        "currency": "EUR"
    },
    "refund_status": "refunded",
    "channel": {
        "code": "sandbox-ee",
        "country": "EE"
    },
    "transaction_id": "87c248c0-3822-4f8e-928e-6176d4b7ccda",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "error": {},
    "timestamp": "2016-12-21T15:08:14.457Z"
}

Refunding errors

In case refunding a consumer fails for any reason, error callback is returned to your API.

Code Error message Description
ERR_800 Generic refund failure. Refund was not applied  
ERR_801 Refund operation failed, retries are allowed  
ERR_802 Charged payment with given operation reference not found  
ERR_803 Payment already in final state, modifications not allowed  
ERR_820 User is blacklisted or blocked  
ERR_821 User account is not enabled  
ERR_822 User account is disabled  
ERR_825 User is not supported by the operator  
ERR_830 Transaction not found  
ERR_835 Refund amount not supported  
ERR_840 Currency not supported or invalid  
ERR_841 Country or operator not supported  
Help us improve our Merchants Portal. Was this article helpful?