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 or digital wallets. 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 ewallet 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 Fortumo Refund 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"
}
|
Fortumo Callback
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 | |