4. API Reference

4.1 Date format

Dates are represented using the ISO 8601 date format. Since the Swish servers create these fields, and the servers are located in Sweden, the timezone used is CET, which is UTC+01:00 or UTC+02:00, depending on whether it is Central European Summer Time (CEST) or not. See the code examples for samples.

4.2 Payment request

The payment request object is used in all three payment request operations: Create, Retrieve and Callback.

Legend:

• M – Mandatory input for Create operation
• O – Optional input for Create operation
• R – Response parameter, should not be specified for Create operation

PropertyTypeDescription
idstringRPayment request ID
payeePaymentReferencestringOPayment reference of the payee, which is the merchant that receives the payment. This reference could be order id or similar.
paymentReferencestringRPayment reference from the bank, of the payment that occurred based on the Payment request. Only available if status is PAID.
callbackUrlstringMURL that Swish will use to notify caller about the outcome of the Payment request. The URL has to use HTTPS.
payerAliasstringONot relevant for q-commerce.
payeeAliasstringMThe Swish number of the payee, that is the merchant.
amountstringMThe amount of money to pay. The amount cannot be less than 1 SEK and not more than 999999999999.99 SEK. A valid value has to be all digits, or all digits, a period and two decimal digits.
currencystringMThe currency to use. SEK is the only supported value.
messagestringOMerchant supplied message about the payment/order. The allowed characters are the letters a-ö, A-Ö, the digits 0-9 and the special characters :;.,?!()”.
statusstringRThe status of the transaction. Possible values: CREATED, PAID, DECLINED, ERROR.
dateCreatedstringRThe time and date when the payment request was created.
datePaidstringRThe time and date when the payment request was paid. Only set if the status is PAID.
errorCodestringRA code indicating what type of error occurred. Only applicable if the status is ERROR.
errorMessagestringRA descriptive error message in English, indicating what of the error occurred. Only set if the status is ERROR.
additionalInformationstringRAdditional information about the error. Only set if the status is ERROR.

4.2.1 Create payment request

POST /api/v1/paymentrequests

HTTP status codes:

Error codeDescription
201 CreatedReturned when a payment request was successfully created. Will return a Location header and a PaymentRequestToken header.
400 Bad RequestReturned when the Create Payment Request 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 payeeAlias in the payment request object is not the same as merchant’s 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.

Potential error codes, returned in Error objects when validation fails, that is HTTP status code 422 is returned:

CodeDescription
FF08paymentReference is invalid
RP03Callback URL is missing or does not use HTTPS
RP01Missing Merchant Swish Number
PA02amount value is missing or not a valid number
AM06Specified amount is less than agreed minimum
AM02Specified amount value is too large
AM03Invalid or missing currency
RP02Incorrectly formatted message
ACMT01Counterpart is not activated

4.2.2 Retrieve payment request

GET api/v1/payment-requests/{id}

Potential HTTP status codes returned:

HTTP status codes:

Status codeDescription
200 OKReturned when Payment request was found. Will return Payment Request Object.
401 UnauthorizedReturned when there are authentication problems with the certificate. Or the Swish number in the certificate is not enrolled. Will return nothing else.
404 Not foundReturned when the Payment request was not found or it was not created by the merchant. Will return nothing else.
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.

4.3 Error objects

An array of error objects is returned when a Create payment request operation fails with status code 422.

PropertyTypeDescription
errorCodestringA code indicating what sort of error occurred.
errorMessagestringA human-readable error message in English, describing the error that occurred.
additionalInformationstringAny additional information about the error.

Example of an array of error objects:

[{
"errorCode": "PA02",
"errorMessage": "Amount value is missing or not a valid number",
"additionalInformation": ""
},{
"errorCode": "AM03",
"errorMessage": "Invalid or missing Currency",
"additionalInformation": "" },{
"errorCode": "RF08",
"errorMessage": "Amount value is too large or amount exceeds the amount
of the original payment minus any previous refunds",
"additionalInformation": "100.00"
}]