Swish Payments

Payment Resource

The payment resource and all general sub-resources can be found in the core payment resources section.

Create Payment

To create a Swish payment, you perform an HTTP POST against the /psp/swish/payments resource. Please read the general information on how to compose a valid HTTP request before proceeding.

An example of a payment creation request is provided below. Each individual Property of the JSON document is described in the following section. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

Request

POST /psp/swish/payments HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "payment": {
       "operation": "Purchase",
       "intent": "Sale",
       "currency": "SEK",
       "prices": [{
           "type": "Swish",
           "amount": 1500,
           "vatAmount": 0
        }],
       "description": "Test Purchase",
       "payerReference": "AB1234",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO",
       "urls": {
           "hostUrls": ["https://example.com", "https://example.net"],
           "paymentUrl": "http://example.com/perform-payment",
           "completeUrl": "https://example.com/payment-completed",
           "cancelUrl": "https://example.com/payment-canceled",
           "callbackUrl": "https://example.com/payment-callback",
           "logoUrl": "https://example.com/logo.png",
           "termsOfServiceUrl": "https://example.com/terms.pdf"
        },
       "payeeInfo": {
           "payeeId": "bbb33dc5-f44e-4af6-afc0-27fb5fa2f63a",
           "payeeReference": "ref-123456",
           "payeeName": "Merchant1",
           "productCategory": "A123",
           "orderReference": "or-123456",
           "subsite": "MySubsite"
        },
       "prefillInfo": {
           "msisdn": "+46xxxxxxxxx" /*we also support international phone numbers
        },
       "swish": {
           "ecomOnlyEnabled": false
        }
    }
}

Properties

PropertyData typeRequiredDescription
payment.operationstringYPurchase
payment.intentstringYSale
payment.currencystringYSEK
payment.prices.typestringYSwish
payment.prices.amountintegerYAmount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 SEK 5000 = 50.00 SEK.
payment.prices.vatAmountintegerYIf the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
payment.descriptionstring(40)YA textual description max 40 characters of the purchase.
payment.payerReferencestringNThe reference to the payer (consumer/end-user) from the merchant system, like mobile number, customer number etc.
payment.userAgentstringYThe user agent reference of the consumer's browser - see user agent definition
payment.languagestringYnb-NO, sv-SE or en-US.
payment.urls.hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
payment.urls.paymentUrlstringNThe URI that PayEx will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. If both cancelUrl and paymentUrl is sent, the paymentUrl will used.
payment.urls.completeUrlstringYThe URI that PayEx will redirect back to when the payment page is completed.
payment.urls.cancelUrlstringYThe URI that PayEx will redirect back to when the user presses the cancel button in the payment page.
payment.urls.callbackUrlstringNThe URI that PayEx will perform an HTTP POST against every time a transaction is created on the payment. See callback for details.
payment.urls.logoUrlstringNThe URI that will be used for showing the customer logo. Must be a picture with at most 50px height and 400px width. Require https.
payment.urls.termsOfServiceUrlstringNA URI that contains your terms and conditions for the payment, to be linked on the payment page. Require https.
payment.payeeInfo.payeeIdstringYThis is the unique id that identifies this payee (like merchant) set by PayEx.
payment.payeeInfo.payeeReferencestring(35)YA unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
payment.payeeInfo.payeeNamestringNThe payee name (like merchant name) that will be displayed to consumer when redirected to PayEx.
payment.payeeInfo.productCategorystringNA product category or number sent in from the payee/merchant. This is not validated by PayEx, but will be passed through the payment process and may be used in the settlement process.
payment.payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
payment.payeeInfo.subsitestring(40)NThe subsite field can be used to perform split settlement on the payment. The subsites must be resolved with PayEx reconciliation before being used.
payment.prefillInfo.msisdnstringNNumber will be prefilled on payment page, if valid. We support international phone numbers defined with country code prefix. ex +45
payment.swish.ecomOnlyEnabledbooleanNIf true you trigger the redirect payment scenario by default.
 
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": {
       "id": "/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f",
       "number": 992308,
       "created": "2017-10-23T08:38:57.2248733Z",
       "instrument": "Swish",
       "operation": "Purchase",
       "intent": "Sale",
       "state": "Ready",
       "currency": "SEK",
       "amount": 0,
       "description": "Test Purchase",
       "payerReference": "AB1234",
       "initiatingSystemUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO",
       "urls": {
           "id": "/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f/urls"
    },
       "payeeInfo": {
           "id": "/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f/payeeinfo"
        }
    },
   "operations": [
        {
           "method": "PATCH",
           "href": "http://localhost:18496/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f",
           "rel": "update-payment-abort"
        },
        {
           "method": "POST",
           "href": "http://localhost:18496/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f/sales",
           "rel": "create-sale"
        }

    ]
}

Operations

A payment resource has a set of operations that can be performed on it, from its creation to its completion. The operations available at any given time vary between payment methods and depends on the current state of the payment resource. A list of possible operations for Swish Payments and their explanation is given below.

Operations
{
   "operations": [
        {
           "method": "PATCH",
           "href": "https://api.externalintegration.payex.com/psp/swish/payments/3648fa94-7fd8-4e32-a14b-08d608f884ff",
           "rel": "update-payment-abort"
        },
        {
           "method": "POST",
           "href": "https://api.externalintegration.payex.com/psp/swish/payments/3648fa94-7fd8-4e32-a14b-08d608f884ff/sales",
           "rel": "create-sale"
        },
        {
           "method": "GET",
           "href": "https://ecom.externalintegration.payex.com/swish/payments/sales/993b479653da83671c074316c7455da05fced9d634431edbb64f3c5f80a863f0",
           "rel": "redirect-sale"
        },
        {
           "method": "GET",
           "href": "https://ecom.externalintegration.payex.com/swish/core/scripts/client/px.swish.client.js?token=cfb9e24832d56fec7ab79709f56accc53d79a699756687d39095b517bc5f011b",
           "rel": "view-payment",
           "contentType": "application/javascript"
        }
    ]
}

Properties

PropertyDescription
hrefThe target URI to perform the operation against.
relThe name of the relation the operation has to the current resource.
methodThe HTTP method to use when performing the operation.

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value. The only thing that should be hard coded in the client is the value of the rel and the request that will be sent in the HTTP body of the request for the given operation.

Operation Description
update-payment-abortAborts the payment before any financial transactions are performed.
create-saleCreates a sales transaction without redirection to a payment page (Direct scenario). Msisdn is required in e-commerce scenario. 
redirect-saleContains the redirect-URI that redirects the consumer to a PayEx hosted payments page prior to creating a sales transaction (Redirect scenario).
view-paymentContains the URI of the JavaScript used to create a Hosted View iframe directly without redirecting the consumer to separate payment page.


Swish transactions

All card specific transactions are described below. Read more about the general transaction resource here.

Sales

The Sales resource lists the sales transactions (one or more) on a specific payment.

Request
GET /psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/sales HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "payment": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
 "sales": {
   "id": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/sale",
   "saleList": [
      {
       "date": "8/13/2019 8:58:23 AM +00:00",
       "payerAlias": "4670XXXXXXX",
       "swishPaymentReference": "8D0A30A7804E40479F88FFBA26111F04",
       "swishStatus": "PAID",
       "id": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/sales/12345678-1234-1234-1234-123456789012",
       "transaction": {
         "id": "12345678-1234-1234-1234-123456789012",
         "created": "2016-09-14T01:01:01.01Z",
         "updated": "2016-09-14T01:01:01.03Z",
         "type": "Sale",
         "state": "Initialized|Completed|Failed",
         "number": 1234567890,
         "amount": 1000,
         "vatAmount": 250,
         "description": "Test transaction",
         "payeeReference": "AH123456",
         "isOperational": "true|false",
         "reconciliationNumber": 737283,
         "operations": []
        }
      }
    ]
  }
}

Create Sales transaction

In e-commerce the consumer/end-user's msisdn(mobile number) is required. This is managed either by sending a POST request as seen below, or by redirecting the end-user to the hosted payment pages. The msisdn is only required for e-commerce. In the m-commerce flow, the consumer uses the device that hosts the Swish app to manage the purchase, making msisdn unneccessary.

e-commerce Request
POST /psp/swish/payments/<paymentId>/sales HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "msisdn": "+46xxxxxxxxx"
    }
}
e-commerce Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f",
   "sale": {
       "date": "23.10.2017 08:39:37 +00:00",
       "paymentRequestToken": "LhXrK84MSpWU2RO09f8kUP-FHiBo-1pB",
       "id": "/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f/sales/6bf31479-623f-418a-d69e-08d519f19722",
       "transaction": {
           "id": "6bf31479-623f-418a-d69e-08d519f19722",
           "created": "2017-10-23T08:39:35.6478733Z",
           "updated": "2017-10-23T08:39:37.3788733Z",
           "type": "Sale",
           "state": "AwaitingActivity",
           "number": 992309,
           "amount": 1500,
           "vatAmount": 0,
           "description": "Test Purchase",
           "payeeReference": "Postman1508747933",
           "isOperational": true,
           "operations": []
        }
    }
}
m-commerce Request
POST /psp/swish/payments/<paymentId>/sales HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
    }
}
m-commerce Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f",
   "sale": {
       "date": "23.10.2017 08:39:37 +00:00",
       "paymentRequestToken": "LhXrK84MSpWU2RO09f8kUP-FHiBo-1pB",
       "id": "/psp/swish/payments/20dfbcb9-587a-4ce9-e63e-08d519f1802f/sales/6bf31479-623f-418a-d69e-08d519f19722",
       "transaction": {
           "id": "6bf31479-623f-418a-d69e-08d519f19722",
           "created": "2017-10-23T08:39:35.6478733Z",
           "updated": "2017-10-23T08:39:37.3788733Z",
           "type": "Sale",
           "state": "AwaitingActivity",
           "number": 992309,
           "amount": 1500,
           "vatAmount": 0,
           "description": "Test Purchase",
           "payeeReference": "Postman1508747933",
           "isOperational": true,
           "operations": [
                {                         
                   "href": "swish://paymentrequest?token=<swishtoken>&callbackurl=<completeUrl>",
                   "method": "GET",
                   "rel": "redirect-app-swish"
                }
            ]
        }
    }
}

Operations
redirect-app-swish is only returned in m-commerce.

The payment now contains a sale transaction with the status (state) "AwaitingActivity". When the consumer confirms the payment a callback request will follow from PayEx. 

Reversals

The Reversals resource list the reversals transactions (one or more) on a specific payment.

Request
GET /psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "reversals": {
       "id": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals",
       "reversalList": [
            {
               "id": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals/12345678-1234-1234-1234-123456789012",
               "transaction": {
                   "id": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
                   "created": "2016-09-14T01:01:01.01Z",
                   "updated": "2016-09-14T01:01:01.03Z",
                   "type": "Reversal",
                   "state": "Initialized|Completed|Failed",
                   "number": 1234567890,
                   "amount": 1000,
                   "vatAmount": 250,
                   "description": "Test transaction",
                   "payeeReference": "AH123456",
                   "isOperational": "TRUE|FALSE",
                   "operations": []
                }
            }
        ]
    }
}

Properties

PropertyTypeDescription
paymentstringThe relative URI of the payment that the reversal transactions belong to.
reversalListarrayThe array of reversal transaction objects.
reversalList[]objectThe reversal transaction object representation of the reversal transaction resource described below.

Create Reversal transaction

You can create a reversal transaction against a completed sales transaction by adding that transaction's payeeReference in the request body.  A callback request will follow from PayEx. 

Request
POST /psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "amount": 1500,
       "vatAmount": 0,
       "description" : "Test Reversal",
       "payeeReference": "ABC123"
    }
}

Properties

PropertyData typeRequiredDescription
transaction.amountintegerYAmount Entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 SEK, 5000 = 50.00 SEK.
transaction.vatAmountintegerYAmount Entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 SEK, 5000 = 50.00 SEK.
transaction.descriptionstringYA textual description of the capture
transaction.payeeReferencestring(35)YA  reference that must match the  payeeReference of the sales transaction you want to reverse. See payeeReference for details.
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "reversal": {
       "id": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals/12345678-1234-1234-1234-123456789012",
       "transaction": {
           "id": "/psp/swish/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Reversal",
           "state": "Initialized|Completed|Failed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "isOperational": "TRUE|FALSE",
           "operations": []
        }
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this capture transaction belongs to.
reversal.idstringThe relative URI of the created capture transaction.
reversal.transactionobjectThe object representation of the generic transaction resource.

Callback

When a change or update from the back-end system are made on a payment or transaction, PayEx will perform a callback to inform the payee (merchant) about this update. Callback functionality is explaned in more detail here.

Problem messages

When performing unsuccessful operations, the eCommerce API will respond with a problem message. We generally use the problem message type and status code to identify the nature of the problem. The problem name and description will often help narrow down the specifics of the problem.

For general information about problem messages and error handling, visit error handling and problem details. 

Error types from Swish and third parties

All Swish error types will have the following URI in front of type: https://api.payex.com/psp/<errordetail>/swish

TypeStatusError codeDetails
externalerror500No error code 
inputerror400FF08Input validation failed (PayeeReference) 
inputerror400BE18Input validation failed (Msisdn) 
inputerror400PA02Input validation failed (Amount) 
inputerror400AM06Input validation failed (Amount) 
inputerror400AM02Input validation failed (Amount)
inputerror400AM03Input validation failed (Currency) 
inputerror500RP02Input validation failed (Description)
configurationerror403RP01Configuration of contract is not correct, or missing settings
configurationerror403ACMT07Configuration of contract is not correct, or missing settings 
systemerror500RP03Unable to complete operation (Invalid callback url) 
swishdeclined403RP06Third party returned error (Duplicate swish payment request) 
swishdeclined403ACMT03Third party returned error (Swish msisdn not enrolled)
swishdeclined403ACMT01Third party returned error (Swish msisdn not enrolled)
swishdeclined403RF02Third party returned error (Reversal declined due to Sale transaction being over 13 months old)
swishdeclined403RF04Third party returned error (Msisdn has changed owner (organization) between sale and reversal)
swishdeclined403RF06Third party returned error (Msisdn has changed owener (SSN) between sale and reversal)
swishdeclined403RF07Third party returned error (Swish rejected transaction)
swishdeclined403FF10Third party returned error (Bank rejected transaction)
usercancelled403BANKIDCLCancelled by user 
swishdeclined403TM01Payment timed out (User din't confirm payment in app)
swishdeclined403DS24 Payment timed out (Bank didn't respond).
systemerror500Any other error code  
Created by Fredrik Köhler on 2018/10/26 11:09