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 |
| amount | Object | Optional | Defines partial refund amount and currency. Contains attributes code and country for specifying the operator and its country. |
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 of the refundable transaction. |
| refund_amount | Object | Mandatory | Defines partial refund amount and currency. Contains attributes value and currency for specifying amount of refund. |
| 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 Fortumo Refund API - initiating a refund
In order to initiate a refund, a POST request towards Fortumo Refund 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. If amount parameter is specified then the refund is considered as a partial refund. If it is not specified then this is a full refund.
1
2
3
4
5
6
7
8
9
10
11 | POST /refunds HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....CgVKRghGWI6-QjMv8JpJi1GarWaQ06CG9d0c1PDFek
{
"payment_operation_reference": "payment_1",
"refund_reason": "API refund by MyCoolCompany",
"merchant": "377b7cdc1716225e7766a7a46e0bbb73",
"operation_reference": "refund_1",
"callback": "https://your-callback-url-here.com"
}
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14 | 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",
"amount": {
"value": 2.00,
"currency": "EUR"
}
}
|
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": 5,
"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"
}
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 | {
"merchant": "d1ed37d8110076db78f06e13a6fc029a",
"operation_reference": "refund_1",
"payment_amount": {
"value": 5.00,
"currency": "EUR"
},
"refund_amount": {
"value": 2.00,
"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:17.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 | |
| ERR_842 | Refund amount exceeds the payment amount | |
| ERR_843 | Partial refund is not supported by the operator | |