Make a full or partial refund back to your customer's bank account

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 nameDescriptionReq.TypeExample
UsernameThe username.YesTextjoe
PasswordThe password.YesTextsecret
OrderIDThe OrderID of the initial deposit.YesText1234567890
AmountThe amount to refund the customer. See format in Handling currencies. Only digits. Use dot (.) as decimal separator.YesText98.02
CurrencyThe currency of the amount to refund the customer.YesTextSEK
AttributesOptional attributes for this method. Send null as value if not used ("Attributes":null). See Attributes.YesObject{"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 nameDescriptionRequiredTypeExample
ExternalReferenceThe 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.NoText123

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 keyDescriptionTypeExample
orderidThe OrderID of the initial deposit.Text1234567890
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.Text1

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 NumberError CodeDescription
602ERROR_FUNCTION_ACCESS_DENIEDThe merchant does not have access to this API method
603ERROR_INSUFFICIENT_FUNDSThe merchant does not have enough balance on their Trustly account to execute the refund.
604ERROR_DUPLICATE_BANK_WITHDRAWALThe refund has already been processed.
607ERROR_HOST_ACCESS_DENIEDThe IP address of the merchant has not been added to Trustly's IP-whitelist.
615ERROR_INVALID_AMOUNTThe amount is incorrect. The amount must be > 0 with 2 decimals, and must not be bigger than the amount in the original order.
616ERROR_INVALID_CREDENTIALSThe username and/or password used in the API call is incorrect.
620ERROR_UNKNOWNThere could be several reasons for this error, for example technical problems with the Trustly service.
622ERROR_INVALID_CURRENCY_CODEThe currency code is invalid. See this page for valid currencies.
623ERROR_INVALID_PARAMETERSSome value or parameter in the refund call does not match the expected format.
636ERROR_UNABLE_TO_VERIFY_RSA_SIGNATUREThe 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.
639ERROR_NO_PUBLIC_KEYNo public key has been configured for the merchant on Trustly's side.
655ERROR_INVALID_ORDER_IDThe OrderID sent in the refund call does not exist.
670ERROR_REFUND_EXCEED_DEPOSIT_VOLUMEThe 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.
671ERROR_DEPOSIT_NOT_CAPTURED_OR_SETTLEDThe refund could not be executed because the deposit failed and did not settle.
672ERROR_MULTIPLE_REFUND_ATTEMPTThis error code will only be returned for deposits done with "Finnish Bank Buttons", where only one refund per deposit can be made.
688ERROR_DUPLICATE_UUIDThis UUID has been used before. It needs to be unique for every new API call.
716ERROR_REFUND_PENDINGA refund is already queued in Trustly's system for this OrderID.
718ERROR_DISABLED_USERThe merchant's user is disabled in Trustly's system.