Payments that Consumers need to be refunded for can be processed via Refunds API.
Endpoint to Refund API:
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: |
|refund_reason ||String ||Mandatory ||Reason of the refund. Should contain the merchant name. Example: |
|merchant ||String ||Mandatory ||Your merchant id. Example: |
|operation_reference ||String ||Mandatory ||Operation reference for the refund. Should be unique for each refund. Example: |
|callback ||String ||Mandatory ||Callback url where refund notifications will be sent. Example: |
Refund callback parameters
|merchant ||String ||Mandatory ||Your Fortumo account's merchant ID. Example: |
|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: |
|payment_amount ||Object ||Mandatory ||Contains attributes |
currency for specifying the amount that will be refunded.
|refund_status ||String ||Optional ||The current status of the refund flow. Example: |
|channel ||Object ||Optional ||Contains attributes |
country for specifying the operator and its country.
|transaction_id ||String ||Mandatory ||Unique billing transaction id. Example: |
|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: |
|error ||Object ||Optional ||In case errors happen an errorcode and description is listed. Example: |
|timestamp ||Datetime ||Mandatory ||Timestamp of the sent callback. Example: |
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: |
|currency ||String, ISO 4217 ||Mandatory ||Currency code. Attribute that specifies the currency in which you are about to refund for the consumer. Example: |
Channel object parameters
|Channel || || || |
|code ||string ||Mandatory ||Specifies the identification code of the carrier. Example: |
|country ||String, ISO 3166-1 alpha-2 ||Mandatory ||Country code. Attribute that specifies the country of your consumer's carrier. Example: |
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.
POST /refunds HTTP/1.1
"refund_reason": "API refund by MyCoolCompany",
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
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?