6 Create refund request

6 Create refund request

Merchants can create refund request to MSS. Once MSS receives a “Refund request” call from a merchant, it validates that the Refund request refers to an available Payment request with status PAID. If validation passes, there are two answers that will be returned from MSS. The first answer is synchronous, the second one is asynchronous. Please note the following:

  1. MSS directly returns a “Refund response” to the merchant.
  2. MSS sends a “Refund confirmation” to the merchant’s callback URL after some delay, default is 10 seconds. The delay is configurable by GetSwish.

In order to create refund request to MSS, Refund request object need to be POST to URL:

HTTPS://mss.cpc.getswish.net/swish-cpcapi/api/v1/refunds/

6.1 Refund request object

The Refund request object is used in all refund operations. The fields marked as mandatory in the list below have to be present in the Create operation.

PropertyTypeMandatory/ OptionalDescription
payerPaymentReferencestringOPayment reference supplied by the Merchant. This could be order id or similar.
originalPaymentReferencestringMPayment reference to the original payment that this refund is for.
paymentReferencestingOPayment reference, from the bank, of the refund payment that occurred based on the created refund. Only available if status is PAID.
callbackUrlstringMURL that Swish will use to notify caller about the outcome of the Refund. The URL has to use HTTPS.
payerAliasstringMThe Swish number of the Merchant that makes the refund payment.
payeeAliasstringOThe Cell phone number of the person that receives the refund payment.
amountstringMThe amount of money to refund. The amount cannot be less than 1 SEK and not more than 999999999999.99 SEK. Moreover, the amount cannot exceed the remaining amount of the original payment that the refund is for.
currencystringMThe currency to use. Only supported value currently is SEK.
messagestringOMerchant supplied message about the refund. Max 50 chars. Allowed characters are the letters a-o ̈, A-Ö, the numbers 0-9 and the special characters :;.,?!()”. For MSS, errorCode as defined in section 6.5 can be set in the message property in order to simulate negative test cases.

6.2 Example positive test cases

curl -v --request POST https:// mss.cpc.getswish.net/swish-cpcapi/api/v1/refunds \
--header "Content-Type: application/json"
--data @- <<! {
"payerPaymentReference": "0123456789",
"originalPaymentReference": "6D6CD7406ECE4542A80152D909EF9F6B",
"callbackUrl": "https://example.com/api/swishcb/refunds",
"payerAlias": "1231234567890",
"amount": "100",
"currency": "SEK",
"message": "Refund for Kingston USB Flash Drive 8 GB"
} !
< HTTP/1.1 201 Created
< Location: https://mss.cpc.getswish.net/swish-cpcapi/api/v1/refunds/ABC2D7406ECE4542A80152D909EF9F6B

6.3 Example negative test cases

curl -v --request POST https://mss.cpc.getswish.net/swish-cpcapi/api/v1/refunds \
--header "Content-Type: application/json" \
--data @- <<! {
"payerPaymentReference": "0123456789",
"originalPaymentReference": "6D6CD7406ECE4542A80152D909EF9F6B",
"callbackUrl": "https://example.com/api/swishcb/refunds",
"payerAlias": "1231234567890",
"amount": "100",
"currency": "SEK",
"message": "ACMT07"
} !
< HTTP/1.1 422 Unprocessable Entity
< Content-Type: application/json
< Transfer-Encoding: chunked
<
[{"errorCode":"ACMT07","errorMessage":"Payee not Enrolled","additionalInformation":null}]

6.4 HTTP status codes

Potential HTTP status codes returned for create refund response:

HTTP status codesReturned scenarios
201 CreatedReturned when Refund was successfully created. Will return a Location header.
400 Bad RequestReturned when Create refund POST operation was malformed.
401 UnauthorizedReturned when there are authentication problems with the certificate. Or the Swish number in the certificate is not enrolled. Will return nothing else.
403 ForbiddenReturned when the payerAlias in the refund object is not the same as Merchants Swish‐number.
415 Unsupported Media TypeReturned when Content‐Type header is not "application/json". Will return nothing else.
422 Unprocessable EntityReturned when there are validation errors. Will return an Array of Error Objects
500 Internal Server ErrorReturned if there was some unknown/unforeseen error that occurred on the server, this should normally not happen. Will return nothing else.
504 Gateway TimeoutReturned when the Bank validation answers take too long and Swish times out. This rarely happens.

6.5 Error codes

Potential Error codes which can be set on create refund request ‘message’ to simulate validation failure in “Refund response” (Http status code 422 is returned on the first answer):


Error codesDescription
FF08PayerPaymentReference is invalid
RP03Callback URL is missing or does not use Https
PA02Amount value is missing or not a valid number
AM06Amount value is too low
RF08Amount value is too large or amount exceeds the amount of the original payment minus any previous refunds. Note: the remaining available amount is put into the additional information field.
AM03Invalid or missing Currency
RP01Payer alias is missing or empty
RP02Invalid Message text
ACMT07Payee not Enrolled
ACMT01Counterpart is not activated
RF02Original Payment not found or original payment is more than than 13 months old
RF03Payer alias in the refund does not match the payee alias in the original payment.
RF04Payer organization number does not match original payment payee organization number.
RF06The Payee SSN (personnummer) in the original payment is not the same as the SSN for the current Payee. Note: Typically this means that the Mobile number has been transferred to another person.
RF07Transaction declined
FF10Bank system processing error
BE18Invalid contact details error

Potential Error codes which can be set on Create refund request ‘message’ to simulate failed “Refund confirmation” (HTTP status code 422 is returned for the second answer):

Error codesDescription
DS24Swish timed out waiting for an answer from the banks after payment was started. Note: If this happens Swish has no knowledge of whether the payment was successful or not. The Merchant should inform its consumer about this and recommend them to check with their bank about the status of this