Payway address service

Target Audience: Users, Stakeholders, Developers

Introduction

This document describes how you can integrate with the Payway Address Service.
The integration is primarily intended towards a Finnish and Swedish market but can also be leveraged by others.
Some features are entirely targeted to a Finnish audience, while others to a Swedish.

Requirements

• Credentials provided by Adeprimo
• HTTPS

Endpoints

Ssn lookup

Looks up information based on a specific ssn. Information is based on the national registry.

Attention

Only works with Swedish ssn's.

Request

curl --request GET \
  --url 'https://payway-address-service-stage.azurewebsites.net/ssnlookup?ssn=YYYYMMDD1234' \
  --header 'authorization: Basic <credentials>' \

Response

{
  "status": "OK",
  "message": null,
  "result": {
    "firstName": "Kalle",
    "lastName": "Anka",
    "streetName": null,
    "streetNumber": null,
    "city": "Ankeborg",
    "zipCode": "12345",
    "country": "SE",
    "streetAddress": "Paradisäppelvägen 111",
    "standardAddressString": "Paradisäppelvägen 111, 12345 Ankeborg, SE"
  }
}

Ssn lookup with address parsing

Looks up information based on a specific ssn. Information is based on the national registry.

Attention

Only works with Swedish ssn's.

Request

curl --request GET \
  --url 'https://payway-address-service-stage.azurewebsites.net/ssnlookupandparse?ssn=YYYYMMDD1234' \
  --header 'authorization: Basic <credentials>' \

Response

{
  "status": "OK",
  "message": null,
  "result": {
    "firstName": "Kalle",
    "lastName": "Anka",
    "street": "Södra Gatunamnsvägen",
    "building": "113-20",
    "staircase": "",
    "apartmentNumber": "",
    "zipCode": "123456",
    "city": "Ankeborg",
    "countryCode": "SE",
    "dropBox": "",
    "location": "",
    "isValid": true
  }
}

Address auto-complete

Search for street addresses. Used for auto-completion in the PPF.
Information is based on https://www.posti.fi/fi/asiakastuki/postinumerotiedostot and updated once a week.

Attention

Only works with Finnish street names. Parameters however can be defined in Swedish or Finnish.

Request

curl --request GET \
  --url 'https://payway-address-service-stage.azurewebsites.net/addressautocomplete?zipCode=65100&query=Strandgatan' \
  --header 'authorization: Basic <credentials>' \  

Response

{
  "status": "OK",
  "message": null,
  "result": [
    "Strandgatan",
    "Strandgatan 10",
    "Strandgatan 11",
    "Strandgatan 12",
    "Strandgatan 13",
    "Strandgatan 14",
    "Strandgatan 15",
    "Strandgatan 16",
    "Strandgatan 17",
    "Strandgatan 18",
    "Strandgatan 19",
    "Strandgatan 2",
    "Strandgatan 20",
    "Strandgatan 21",
    "Strandgatan 22",
    "Strandgatan 23",
    "Strandgatan 24",
    "Strandgatan 25",
    "Strandgatan 26",
    "Strandgatan 27",
    "Strandgatan 28",
    "Strandgatan 29",
    "Strandgatan 3",
    "Strandgatan 30",
    "Strandgatan 4",
    "Strandgatan 5",
    "Strandgatan 6",
    "Strandgatan 7",
    "Strandgatan 8",
    "Strandgatan 9"
  ]
}

Location lookup

Lookup information for a specific zip code.

Attention

Only works with Finnish zip codes.

Request

curl --request GET \
  --url 'https://payway-address-service-stage.azurewebsites.net/locationlookup?zipCode=65100&languageCode=fi' \
  --header 'authorization: Basic <credentials>' \  

Response

{
  "status": "OK",
  "message": null,
  "result": {
    "zipCode": "65100",
    "city": "VAASA",
    "country": "FI"
  }
}

Parse address

Parse an address to be compliant with the Payway address format.

Request

curl --request POST \
  --url https://payway-address-service-stage.azurewebsites.net/parse \
  --header 'authorization: Basic <credentials>' \
  --header 'content-type: application/json' \  
  --data '{
    "FirstName" : "Bill",
    "LastName" : "Gates",
    "StreetAddress" : "Silicon Valley Road 97a A52 Microsoft",
    "City" : "San Jose",
    "ZipCode" : "00 100",
    "Country" : "fi",
    "Dropbox": "PL 123"
}'

Response

{
  "status": "OK",
  "message": null,
  "result": {
    "firstName": "Firstname",
    "lastName": "Lastname",
    "street": "Silicon Valley Road",
    "building": "97a",
    "staircase": "A",
    "apartmentNumber": "52",
    "zipCode": "00100",
    "city": "San Jose",
    "countryCode": "FI",
    "dropBox": "PL 123",
    "isValid": true,
    "Location": "Microsoft"
  }
}

Errors

All errors returned conform to the same format.

Format

{
  "status": "FAILED",
  "message": "Internal server error",
  "result": null
}