Solutions Swish for merchants API manuals

11. Swish API Description

11. Swish API Description

11.1 Payment Request

Payment requests are created/retrieved with the operations listed below. There are two main flows to this use case, one for Swish m-commerce and one for Swish e-commerce. The main difference is that in the Swish e-commerce case the consumer is prompted for his/her mobile phone number, and then the consumer has to manually open the Swish app. But in the Swish m-commerce case the consumer’s mobile phone number is initially not known to the merchant. So instead, in this case, the API returns a Payment request token. This token is used to build a so called Swish URL, which the merchant can use to call the Swish app from their app. The Payment request token is then a parameter to the Swish URL. Once the paymentrequest reached to final state (either Paid, Timeout or Error), the Merchant provided Callback URL will be called by Swish. Even though this callback contains the payment status information, the merchant server should retrieve the result of the payment request directly from the Swish server (refer to Retrieve Payment Request for further details).These flows are illustrated in the pictures below.

11.1.1 Swish e-commerce

11.1.2 Swish m-commerce

11.1.3 Create Payment Request

POST /api/v1/paymentrequests

The Http request body have to contain a Payment Request Object.

Potential Http status codes returned:

  • 201 Created: Returned when Payment request was successfully created. Will return a Location header and if it is Swish m-commerce case, it will also return PaymentRequestToken header.
  • 400 Bad Request: Returned when the Create Payment Request operation was malformed.
  • 401 Unauthorized: Returned when there are authentication problems with the certificate. Or the Swish number in the certificate is not enrolled. Will return nothing else.
  • 403 Forbidden: Returned when the payeeAlias in the payment request object is not the same as merchant’s Swish number.
  • 415 Unsupported Media Type: Returned when Content-Type header is not “application/json”. Will return nothing else.
  • 422 Unprocessable Entity: Returned when there are validation errors. Will return an Array of Error Objects.
  • 500 Internal Server Error: Returned 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 on Error Objects when validation fails (HTTP status code 422 is returned):

  • FF08 – PaymentReference is invalid
  • RP03 – Callback URL is missing or does not use Https
  • BE18 – Payer alias is invalid
  • RP01 – Missing Merchant Swish Number
  • PA02 – Amount value is missing or not a valid number
  • AM06 – Specified transaction amount is less than agreed minimum
  • AM02 – Amount value is too large
  • AM03 – Invalid or missing Currency
  • RP02 – Wrong formated message
  • RP06 – A payment request already exist for that payer. Only applicable for Swish ecommerce.
  • ACMT03 – Payer not Enrolled
  • ACMT01 – Counterpart is not activated
  • ACMT07 – Payee not Enrolled

Create Payment request example (Swish e-commerce):


curl -v --request POST https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests \
--header "Content-Type: application/json" \
--data @- <<!
{
"payeePaymentReference": "0123456789",
"callbackUrl": "https://example.com/api/swishcb/paymentrequests",
"payerAlias": "46701234567",
"payeeAlias": "1234760039",
"amount": "100",
"currency": "SEK",
"message": "Kingston USB Flash Drive 8 GB"
}
!
< HTTP/1.1 201 Created
< Location: https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/AB23D7406ECE4542A80152D909EF9F6B

Create Payment request example (Swish m-commerce):


curl -v --request POST https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests \
--header "Content-Type: application/json"
--data @- <<!
{
"payeePaymentReference": "0123456789",
"callbackUrl": "https://example.com/api/swishcb/paymentrequests",
"payeeAlias": "1234760039",
"amount": "100",
"currency": "SEK",
"message": "Kingston USB Flash Drive 8 GB"
}
!
< HTTP/1.1 201 Created
< Location: https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/AB23D7406ECE4542A80152D909EF9F6B
< PaymentRequestToken: f34DS34lfd0d03fdDselkfd3ffk21

The PaymentRequestToken is then used to open the swish app, using the Custom URL Scheme e.g.:

swish://paymentrequest?token=f34DS34lfd0d03fdDselkfd3ffk21

11.1.4 Retrieve Payment Request

GET /api/v1/paymentrequests/{id}

Potential HTTP status codes returned:

  • 200 OK: Returned when Payment request was found. Will return Payment Request Object.
  • 401 Unauthorized: Returned when there are authentication problems with the certificate. Or the Swish number in the certificate is not enrolled. Will return nothing else.
  • 404 Not found: Returned when the Payment request was not found or it was not created by the merchant. Will return nothing else.
  • 500 Internal Server Error: Returned if there was some unknown/unforeseen error that occurred on the server, this should normally not happen. Will return nothing else.

Retrieve Payment request example (Swish e-commerce):


curl -v --request GET https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/AB23D7406ECE4542A80152D909EF9F6B
< HTTP/1.1 200 OK
{
"id": "AB23D7406ECE4542A80152D909EF9F6B",
"payeePaymentReference": "0123456789",
"paymentReference": "6D6CD7406ECE4542A80152D909EF9F6B",
"callbackUrl": "https://example.com/api/swishcb/paymentrequests",
"payerAlias": "46701234567",
"payeeAlias": "1231234567890",
"amount": "100",
"currency", "SEK",
"message": "Kingston USB Flash Drive 8 GB",
"status": "PAID",
"dateCreated": "2015-02-19T22:01:53+01:00",
"datePaid": "2015-02-19T22:03:53+01:00"
}

11.1.5 Callback

Swish will make a callback HTTPS POST request, with the Payment Request Object, to the Callback URL supplied in the Create Payment Request operation when either of the following events (status) happens:

  • PAID – The payment was successful
  • DECLINED – The payer declined to make the payment
  • ERROR – Some error occurred, like payment was blocked, payment request timed out etc. See list of error codes for all potential error conditions.

A payment request has to be accepted or declined by the consumer within three (3) minutes for e-commerce and three (3) minutes for m-commerce. When the time has elapsed an ERROR status is returned to the Callback URL. If the consumer accepts the payment request a status is returned to the Callback URL within 12 seconds.

The callback endpoint has to use HTTPS and we highly recommend IP filtering as well. It is however up to the merchant to make sure the endpoint is available. Swish will only make the callback request once, if the merchant has not received a callback response after the timeout, the merchant can choose to call the Retrieve Payment Request. Swish will always try to make a callback request before the timeout period, but if it times out, then a timeout callback is sent with status ERROR and the error code will have value TM01.

11.2 Payment Refund

Refunds are initiated based on a Payment reference from an earlier payment. To make a refund create first a Refund, similar to how you create a payment request, and then you will receive a reference to the refund, but the result of the refund is returned in a Callback, similar to how payment request works. A refund normally completes much faster than a payment request, but a callback is used because the actual payment might take a long time, normally it does not, but since it might, the result is returned asynchronously in the callback. The callback, in the happy case, will return an intermediate response with status DEBITED. This response is guaranteed to have returned in under 10 s or you will get an ERROR response. The DEBITED response means that the money has been taken from the merchants (payers) account, but has not been put into the payees account yet. Normally this should happen very soon afterwards, but this “might” take a long time. Moreover, it is not guaranteed to succeed, in other words the receiving bank might refuse to put money into the account. In that case the Commerce customer will receive an ERROR response and the money is put back into the Commerce customers account. So these are the potential callback scenarios:

  1. Happy case: DEBITED, PAID
  2. Early error: ERROR
  3. Late error: DEBITED, ERROR

So in other words there is a tradeoff here, between speed and accuracy that the merchant needs to make:

  1. Use the early fast guaranteed response of DEBITED to give a quick response that might turn out to be inaccurate later on.
  2. Ignore the DEBITED response and wait for the PAID response that is always accurate but not always fast.

11.2.1 Create Refund

POST /api/v1/refunds

The Http request body have to contain a Refund Object.

Potential Http status codes returned:

  • 201 Created: Returned when Refund was successfully created. Will return a Location header.
  • 400 Bad Request: Returned when Create refund POST operation was malformed.
  • 401 Unauthorized: Returned when there are authentication problems with the certificate. Or the Swish number in the certificate is not enrolled. Will return nothing else.
  • 403 Forbidden: Returned when the payerAlias in the refund object is not the same as merchant’s Swish number.
  • 415 Unsupported Media Type: Returned when Content-Type header is not “application/json”. Will return nothing else.
  • 422 Unprocessable Entity: Returned when there are validation errors. Will return an Array of Error Objects.
  • 500 Internal Server Error: Returned if there was some unknown/unforeseen error that occurred on the server, this should normally not happen. Will return nothing else.
  • 504 Gateway Timeout: Returned when the Bank validation answers take too long and Swish times out. This rarely happens.

Potential Error codes returned on Error Objects when validation fails (Http status code 422 is returned):

  • FF08 – Payment Reference is invalid
  • RP03 – Callback URL is missing or does not use Https
  • PA02 – Amount value is missing or not a valid number
  • AM06 – Specified transaction amount is less than agreed minimum
  • RF08 – Amount 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.
    
Note: the remaining available amount is put into the additional information field.
  • AM03 – Invalid or missing Currency
  • RP01 – Missing merchant Swish Number
  • RP02 – Wrong formatted message
  • ACMT07 – Payee not Enrolled
  • ACMT01 – Counterpart is not activated
  • RF02 – Original Payment not found or original payment is more than 13 months old
  • RF03 – Payer alias in the refund does not match the payee alias in the original payment
  • RF04 – Payer organization number do not match original payment payee organization number.
  • RF06 – The Payer SSN 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.
  • RF07 – Transaction declined
  • FF10 – Bank system processing error
  • BE18 – Payer alias is invalid

Create Refund example:

curl -v --request POST https://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": "1231181189",
"amount": "100",
"currency": "SEK",
"message": "Refund for Kingston USB Flash Drive 8 GB"
}
!
<HTTP/1.1 201 Created
<Location: https://cpc.getswish.net/swish-cpcapi/api/v1/refunds/ABC2D7406ECE4542A80152D909EF9F6B

11.2.2 Retrieve Refund

GET /api/v1/refunds/{id}

Potential HTTP status codes returned:

  • 200 OK: Returned when refund was found. Will return Refund Object.
  • 401 Unauthorized: Returned when there are authentication problems with the certificate. Or the Swish number in the certificate is not enrolled. Will return nothing else.
  • 404 Not found: Returned when no refund was found or it was not created by the merchant. Will return nothing else.
  • 500 Internal Server Error: Returned if there was some unknown/unforeseen error that occurred on the server, this should normally not happen. Will return nothing else.

Possible statuses:

  • VALIDATED – Refund ongoing
  • DEBITED – Money has been withdrawn from your account
  • PAID – The payment was successful
  • ERROR – Some error occurred. See list of error codes for all potential error conditions.

Retrieve Refund example:

curl -v --request GET https://cpc.getswish.net/swish-cpcapi/api/v1/refunds/ABC2D7406ECE4542A80152D909EF9F6B
< HTTP/1.1 200 OK
{
"id": "ABC2D7406ECE4542A80152D909EF9F6B",
"payerPaymentReference": "0123456789",
"originalPaymentReference": "6D6CD7406ECE4542A80152D909EF9F6B",
"callbackUrl": "https://example.com/api/swishcb/refunds",
"payerAlias": "1231181189",
"payeeAlias": "46701234567",
"amount": "100",
"currency": "SEK",
"message": "Refund for Kingston USB Flash Drive 8 GB",
"status": "PAID",
"dateCreated": "2015-02-19T22:01:53+01:00",
"datePaid": "2015-02-19T22:03:53+01:00"
}

11.2.3 Callback

Swish will make a callback HTTPS POST request, with the Refund Object, to the Callback URL supplied in the Create Refund operation when either of the following events (status) happens:

  • DEBITED – Money has been withdrawn from your account
  • PAID – The payment was successful
  • ERROR – Some error occurred. See list of error codes for all potential error conditions.

11.3 Objects

The date fields use the date format. Since the Swish server creates these date fields, and the servers are located in Sweden, the time-zone used is, which is or, depending on whether it is or not. See the code examples for samples.

11.3.1 Payment Request Object

The Payment Request Object is used in all 3 Payment Request operations (Create, Retrieve and Callback). The fields that are mandatory are for the Create operation, but of course those fields will also be available on the other operations.

Legend:

  • M – Mandatory input parameter (for Create operation)
  • O – Optional input parameter (for Create operation)
  • R – Response parameter (should not be supplied in 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.
payerAliasstringOThe registered Cell phone number of the person that makes the payment. It can only contain numbers and has to be at least 8 and at most 15 numbers. It also needs to match the following format in order to be found in Swish: countrycode + cell phone number (without leading zero). E.g.:n46712345678
payeeAliasstringMThe Swish number of the payee
amountstringMThe amount of money to pay. The amount cannot be less than 1 SEK and not more than 999999999999.99 SEK. Valid value have to be all numbers or with 2 digit decimal seperated with a period.
currencystringMThe currency to use. Only supported value currently is SEK.
messagestringOMerchant supplied message about the payment/order. Max 50 chars. Allowed characters are the letters a-ö, A-Ö, the numbers 0-9 and the special characters :;.,?!()”.
statusstringRThe status of the transaction. Possible values: CREATED, PAID, DECLINED, ERROR.
dateCreatedstringRThe time and date that the payment request was created.
datePaidstringRThe time and date that the payment request was paid. Only applicable if status was PAID.
errorCodestringRA code indicating what type of error occurred. Only applicable if status is ERROR.
errorMessagestringRA descriptive error message (in English) indicating what type of error occurred. Only applicable if status is ERROR
additionalInformationstringRAdditional information about the error. Only applicable if status is ERROR.

Potential Error codes values:

CodeDescription
ACMT03Payer not Enrolled
ACMT01Counterpart is not activated
ACMT07Payee not Enrolled
RF07Transaction declined. The payment was unfortunately declined. A reason for the decline could be that the payer have exceeded their defined Swish limit. Please advise the payer to check with their bank.
BANKIDCLPayer cancelled bankid signing
FF10Bank system processing error
TM01Swish timed out before the payment was started
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 payment.
BANKIDONGOINGBankID already in use
BANKIDUNKNBankID are not able to authorize the payment.

11.3.2 Refund Object

The Refund Object is used in all 3 Refund operations (Create, Retrieve and Callback). The fields that are mandatory are for the Create operation, but of course those fields will also be available on the other operations.

Legend:

  • M – Mandatory input parameter (for Create operation)
  • O – Optional input parameter (for Create operation)
  • R – Response parameter (should not be supplied in Create operation)
PropertyTypeDescription
idstringRRefund ID
payerPaymentReferencestringOPayment reference supplied by the merchant. This could be order id or similar.
originalPaymentReferencestringMReference of the original payment that this refund is for
paymentReferencestringRReference 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.
payeeAliasstringRThe 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 can not 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-ö, A-Ö, the numbers 0-9 and the special characters :;.,?!()”.
statusstringRThe status of the refund transaction. Possible values:VALIDATED, DEBITED, PAID, ERROR.
dateCreatedstringRThe time and date that the payment refund was created.
datePaidstringRThe time and date that the payment refund was paid.
errorCodestringRA code indicating what type of error occurred. Only applicable if status is ERROR.
errorMessagestringRA descriptive error message (in English) indicating what type of error occurred. Only applicable if status is ERROR
additionalInformationstringRAdditional information about the error. Only applicable if status is ERROR.

Potential Error codes values:

CodeDescription
ACMT07Payee not Enrolled
ACMT01Counterpart is not activated
RF07Transaction declined. Please contact your bank.
FF10Bank system processing error
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 payment.

11.3.3 Error Object

PropertyTypeDescription
errorCodestringA code indicating what type of error occurred.
errorMessagestringA descriptive error message (in English) indicating what type of error occurred.
additionalInformationstringAdditional information about the error

Example: 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"
}]