Refund

Overview

Refunds the customer on a previous Deposit or Charge.

The Refund will always be made to the same bank account that was used in the original payment.

You must have sufficient funds in your merchant account to make the refund. No credit is given. If the Deposit has not yet been settled when the refund request is received, the refund will be queued and executed once the money for the deposit has been received.

It's possible to do multiple partial refunds on the same Deposit as long as the total refund amount does not exceed the original Deposit amount.

Request example

{
    "method": "Refund",
    "params": {
        "Signature": "W6JH1qeGCt...JOi5E80Adw==",
        "UUID": "8bedfbd4-8181-38e1-f0be-f360171aefc6",
        "Data": {
            "Username": "merchant_username",
            "Password": "merchant_password",
            "OrderID": "1187741486",
            "Amount": "30.00",
            "Currency": "EUR",
            "Attributes": null
        }
    },
    "version": 1.1
}

Request parameters

Parameter name	Description	Req.	Type	Example
Username	The username.	Yes	Text	joe
Password	The password.	Yes	Text	secret
OrderID	The OrderID of the initial deposit.	Yes	Text	1234567890
Amount	The amount to refund the customer. See format in Handling currencies. Only digits. Use dot (.) as decimal separator.	Yes	Text	98.02
Currency	The currency of the amount to refund the customer.	Yes	Text	SEK
Attributes	Optional attributes for this method. Send null as value if not used ("Attributes":null). See Attributes.	Yes	Object	{"ExternalReference ":"123"}

Attributes

The parameter Attributes is an object of attributes.

Note: New attributes may be added in future versions of the API, but existing attributes will never be removed.

Attribute name	Description	Required	Type	Example
ExternalReference	The ExternalReference is a reference set by the merchant for any purpose and does not need to be unique for every API call. The ExternalReference will be included in version 1.2 of the settlement report. See ViewAutomaticSettlementDetailsCSV.	No	Text	123

Response example

{
    "version": "1.1",
    "result": {
        "signature": "CeYDdgTi...jfzXlR3iSLQjt5Yl9w==",
        "method": "Refund",
        "data": {
            "result": "1",
            "orderid": "1187741486"
        },
        "uuid": "8bedfbd4-8181-38e1-f0be-f360171aefc6"
    }
}

Response attributes

The result returned is a hash with the following attributes

Hash key	Description	Type	Example
orderid	The OrderID of the initial deposit.	Text	1234567890
result	"1" if the refund request is accepted by Trustly's system. If the refund request is not accepted, you will get an error code back.	Text	1

Failed Refunds

In case an error occurs when processing the Refund (after the "result" : "1" response has been sent), a Credit notification will be sent to the NotificationURL provided in the original Deposit call so that the merchant can flag the Refund as failed in their system. This is uncommon but can happen for example if the end user's bank account has been closed. In this case, the funds will be returned to the merchant's Trustly account balance.

Notifications

A Payout confirmation notification can be sent to the merchant's NotificationURL when the transfer has been confirmed. Note: this notification is not enabled by default. Please speak to your Trustly contact person if you want to have it enabled.

Error codes

These error codes can be returned for Refund calls. To handle errors, see Error handling.

Error Number	Error Code	Description
602	ERROR_FUNCTION_ACCESS_DENIED	The merchant does not have access to this API method
603	ERROR_INSUFFICIENT_FUNDS	The merchant does not have enough balance on their Trustly account to execute the refund.
604	ERROR_DUPLICATE_BANK_WITHDRAWAL	The refund has already been processed.
607	ERROR_HOST_ACCESS_DENIED	The IP address of the merchant has not been added to Trustly's IP-whitelist.
615	ERROR_INVALID_AMOUNT	The amount is incorrect. The amount must be > 0 with 2 decimals, and must not be bigger than the amount in the original order.
616	ERROR_INVALID_CREDENTIALS	The username and/or password used in the API call is incorrect.
620	ERROR_UNKNOWN	There could be several reasons for this error, for example technical problems with the Trustly service.
622	ERROR_INVALID_CURRENCY_CODE	The currency code is invalid. See this page for valid currencies.
623	ERROR_INVALID_PARAMETERS	Some value or parameter in the refund call does not match the expected format.
636	ERROR_UNABLE_TO_VERIFY_RSA_SIGNATURE	The signature could not be verified using the merchant's public key. Either the wrong private key was used to generate the signature, or the the data object used to create the signature was serialised incorrectly.
639	ERROR_NO_PUBLIC_KEY	No public key has been configured for the merchant on Trustly's side.
655	ERROR_INVALID_ORDER_ID	The OrderID sent in the refund call does not exist.
670	ERROR_REFUND_EXCEED_DEPOSIT_VOLUME	The refund amount is larger than the deposit amount. Or in case of multiple partial refunds: the refund amount is larger than the amount that is left to refund for the given deposit.
671	ERROR_DEPOSIT_NOT_CAPTURED_OR_SETTLED	The refund could not be executed because the deposit failed and did not settle.
672	ERROR_MULTIPLE_REFUND_ATTEMPT	This error code will only be returned for deposits done with "Finnish Bank Buttons", where only one refund per deposit can be made.
688	ERROR_DUPLICATE_UUID	This UUID has been used before. It needs to be unique for every new API call.
716	ERROR_REFUND_PENDING	A refund is already queued in Trustly's system for this OrderID.
718	ERROR_DISABLED_USER	The merchant's user is disabled in Trustly's system.