swish-module

This is a library to integrate the Swedish payment system Swish into your application. This library uses the Swish API to create and handle payments and refunds.

Installation

With yarn

yarn add swish-module

With npm

npm install swish-module

Usage

Pre-requisites

Before using the Swish API in production, some steps have to be taken. You can follow this guide that is provided by Swish.

You can still develop on this API without having to go through the steps above. You can use the test environment provided by Swish. You can find the test environment credentials here.

The Swish flow

Initialize the API

To initialize the API, you need to have 3 files, a private key, a certificate and a CA certificate. You can find these files in the guide above. You can also find them in the test environment credentials.

To initialize the API, you can use the following code:

const swish = new Swish({
    cert: "./certs/Swish_Merchant_TestCertificate_1234679304.pem",
    key: "./certs/Swish_Merchant_TestCertificate_1234679304.key",
    ca: "./certs/Swish_TLS_RootCA.pem",
  });

Create a payment

To create a payment, you can use the following code:

const req = await swish.createPaymentRequest(
    {
      payeePaymentReference: "1234567890",
      callbackUrl: "https://example.com/api/swishcb/paymentrequests",
      payeeAlias: "1234679304",
      currency: "SEK",
      payerAlias: "460721282737",
      amount: "100",
      message: "Test message",
    },
    true
);

Table of the function takes in 2 parameters, the options that are as following:

Name	Type	Description	optional
payeePaymentReference	string	A unique reference to the payment.	true
callbackUrl	string	The URL that Swish will send a callback to when the payment status changes.	false
payeeAlias	string	The Swish number of the merchant.	true
currency	string	The currency of the payment.	false
payerAlias	string	The Swish phone number of the customer.	false
amount	string	The amount of the payment.	false
message	string	A message that will be shown to the customer.	true

The function also takes in a boolean, which is if the payment is a test payment or not.

The function is going to return 3 things:

• uuid: the generated UUID of the payment, which is a 32 hexadecimal (16- based) digits.
• status: The status code of the request.
• location: The location of the payment.

Get a payment

To get information about a payment, you can use the following code:

const payment = await swish.retrievePaymentRequest(req.location); // we send in the location from the createPaymentRequest function

This function is going to return the payment information.

Refund a payment

To refund a payment, you can use the following code:

const paymentRefund = await paymentHandler.createRefundRequest(req.uuid, {
    originalPaymentReference: "1234567890",
    callbackUrl: "https://example.com/api/swishcb/refunds",
    payerAlias: "460721282737",
    payeeAlias: "1234679304",
    currency: "SEK",
    amount: "50",
    message: "Test message",
  }, true);

Table of the function takes in 3 parameters, the first one is the UUID of the payment, the second one is the options that are as following:

Name	Type	Description	optional
originalPaymentReference	string	The original payment reference.	false
callbackUrl	string	The URL that Swish will send a callback to when the payment status changes.	false
payerAlias	string	The Swish phone number of the customer.	false
payeeAlias	string	The Swish number of the merchant.	false
currency	string	The currency of the payment.	false
amount	string	The amount of the payment.	false
message	string	A message that will be shown to the customer.	true
payerPaymentReference	string	Payment reference supplied by the merchant. This reference could be order id or similar. Allowed characters are a-z A-Z 0-9 and length must be between 1 and 35 characters.	true

The function also takes in a boolean, which is if the payment is a test payment or not.

The function is going to return 3 things:

• uuid: the generated UUID of the payment, which is a 32 hexadecimal (16- based) digits.
• status: The status code of the request.
• location: The location of the payment.

Generate a QR code

In Swish a user can use a QR code to issue a payment, you can use the following code to generate a QR code:

const qr = await paymentHandler.generateQRCode({
    payee: "1234679304",
    amount: {
      value: 100,
    },
    message: {
      value: "Test message",
      editable: true,
    }
  })

The function takes in 1 parameter, which is the options that are as following:

Name	Type	Description	parameters	optional
payee	string	The Swish number of the merchant.	false
amount	object	The amount of the payment.	valu, editable (optional)	true
message	object	A message that will be shown to the customer.	value, editable (optional)	true
size	number	The size of the QR code.	true
border	number	The border of the QR code.	true

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

I am also open to suggestions on how to improve this package, where I am a lone developer, so I am not the best at everything :)