Solutions Swish for merchants Test Connection

4 Create payment request

4 Create payment request

4. Payment request

Merchants can create payment request for both E-Commerce and M-Commerce to MSS. Once MSS receives a “create payment request” call from merchants, 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 “Payment request created” response to the merchants. In case of M- Commerce the response will also contain a Token, unique for each payment request.
  2. MSS sends a “Payment confirmation” to the merchant’s callback URL after some delay, default is five seconds. The delay is only configurable by Getswish.

In order to create payment request to MSS, Payment request object need to be POST to URL:

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

4.1 Payment request object

The Payment Request Object is used in all payment request operations. The fields marked as mandatory in the list below have to be present in the Create operation.

PropertyTypeMandatory/ OptionalDescription
payeePaymentReferencestringOPayment reference of the payee, which is the Merchant that receives the payment. This reference could be order id or similar.
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: country code + cell phone number (without leading zero). E.g.: 46712345678
payeeAliasstringMThe Swish number of the payee. It needs to match with Merchant Swish number.
amountstringMThe amount of money to pay. The amount cannot be less than 1 SEK and not more than 999999999999.99 SEK. Valid value has to be all numbers or with 2 digit decimal
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-o ̈, A-Ö, the numbers 0-9 and the special characters :;.,?!()”. For MSS, errorCode as defined in section 0 can be set in the message property in order to simulate negative

4.2.1 Example positive test cases - E-Commerce

A “create payment request” call from merchants with the payer’s mobile telephone number is for E- Commerce.

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

4.2.2 Example positive test cases - M-Commerce

A “create payment request” call from merchants without the payer’s mobile telephone number is for M-Commerce.

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

4.3 Example negative test cases

A “create payment request” call from merchants with errorCode in property ‘message’.

curl -v --request POST https://mss.cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/ \
--header "Content-Type: application/json" \
--data @- <<!
{
"payeePaymentReference": "0123456789",
"callbackUrl": "https://example.com/api/swishcb/paymentrequests",
"payeeAlias": "1231181189",
"amount": "100", "currency": "SEK", "message": "BE18"
}
!
< HTTP/1.1 422 Unprocessable Entity
< Content-Type: application/json
< Transfer-Encoding: chunked
<
[{"errorCode":"BE18","errorMessage":"In this case incorrect MSISDN","additionalInformation":null}]

4.4 HTTP status codes

Potential HTTP status codes returned for create payment response:

HTTP status codesReturned scenarios
201 CreatedReturned when Payment request was successfully created. Will return a Location header and if it is M-Commerce case, it will also return 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 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.

4.5 Error codes

Potential Error codes which can be set on Create payment request ‘message’ to simulate validation failure in the “Payment request created” response (HTTP status code 422 is returned for the first answer):

Error codesDescription
FF08PayeePaymentReference is invalid
RP03Callback URL is missing or does not use Https
BE18Payer alias is invalid
RP01Payee alias is missing or empty
PA02Amount value is missing or not a valid number
AM06Amount value is too low
AM02Amount value is too large
AM03Invalid or missing Currency
RP02Wrong formatted message
RP06Another active PaymentRequest already exists for this payerAlias. Only applicable for E-Commerce.
ACMT03Payer not Enrolled
ACMT01Counterpart is not activated
ACMT07Payee not Enrolled

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

Error codesDescription
RF07Transaction declined
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.