Paynova Invoice as a Service: Direct API Integration Overview Paynova provides a direct API integration via its REST API for Invoice as a Serivce. This means that the merchant's web shop communicates directly with Paynova's API to complete the payment without redriecting the user to Paynova.

The merchant captures all necessary information in their own checkout and then sends the transaction request to Paynova. Paynova responds with a transaction status (OK, Declined) and the transaction details.

The merchant can then display the transaction results however they choose, for example by displaying an order confirmation page.

User Experience Becuase the invoice payment is processeed via a direct API integration, the merchant can customize the user experience in the checkout.

The following elements, however, are required to be rendered: Function to retrieve user's address (folkbokföringsadress) Function to display all payment methods available for the current purchase Function for user to confirm the purchase (e.g. "Complete purchase", "Pay now") These are explained in detail below.

Payment Flow The entire payment flow is handled with synchronous API calls. The following 5 API calls are used:

Step 1: Get checkout assets 1.  Get Addresses 2.  Get Payment Options

Step 2: Process payment 1.  Create Order 2.  Authorize Payment

Step 3: Finalize payment 1.  Finalize Authorization

API Authentication The API uses Basic Authentication. Please use the username, password and secret key you received from Merchant Support.

Get Adresses GET /addresses/{countryCode}/{governmentId}

The first step is to fill in the customer's name and address information in your checkout. For invoice and installment purchases, this address must match the address in Paynova's database (Swedish folkbokföringsadress).

To retrieve this address, send a GET request with the customer's personal number and country code in the URL. Then use the data in the response to fill in the appropriate fields in your checkout.

We recommend that you lock these fields and disable editing of these fields after the address has been retrieved.

Example request GET /addresses/SE/19890115‐7993

Example response { "governmentId": "198901157993", "countryCode": "SE", "addresses": [ { "name": { "companyName": null, "title": null, "firstName": "NAMNI", "middleNames": null, "lastName": "ENAMNI", "suffix": null }, "address": { "type": "legal", "street1": "GATUADRESS 77", "street2": null, "street3": null, "street4": null, "city": "LANDSKRONA", "postalCode": "26151", "regionCode": null, "countryCode": "SE" } } ], "status": { "isSuccess": true,

"errorNumber": 0, "statusKey": "SUCCESS", "statusMessage": "The operation was successful.", "errors": null, "exceptionDetails": null } }

Get Payment Options POST /paymentoptions

Get Payment Options retrieves all the available payment options for the current purchase based on the total amount, currency and country.

Use the information from the response to display the available payment options to the user.

Example request POST /paymentoptions

{     "TotalAmount": 125.00,     "CurrencyCode": "SEK",     "PaymentChannelId": 1,     "CountryCode": "SE",     "LanguageCode": "SWE" }

Example response { "status": {

"isSuccess": true, "errorNumber": 0, "statusKey": "SUCCESS", "statusMessage": "The operation was successful.", "errors": null, "exceptionDetails": null }, "availablePaymentMethods": [ { "paymentMethodId": 104, "paymentMethodProductId": null, "displayName": "SEB", "group": { "key": "online_bank", "displayName": "Internetbank" }, "interestRate": null, "notificationFee": null, "setupFee": null, "numberOfInstallments": null, "installmentPeriod": null, "installmentUnit": null, "legalDocuments": null, "addressTypeRestrictions": [ ] }, { "paymentMethodId": 103, "paymentMethodProductId": null, "displayName": "Handelsbanken", "group": { "key": "online_bank", "displayName": "Internetbank" }, "interestRate": null, "notificationFee": null,

"setupFee": null, "numberOfInstallments": null, "installmentPeriod": null, "installmentUnit": null, "legalDocuments": null, "addressTypeRestrictions": [ ] }, { "paymentMethodId": 101, "paymentMethodProductId": null, "displayName": "Nordea", "group": { "key": "online_bank", "displayName": "Internetbank" }, "interestRate": null, "notificationFee": null, "setupFee": null, "numberOfInstallments": null, "installmentPeriod": null, "installmentUnit": null, "legalDocuments": null, "addressTypeRestrictions": [ ] }, { "paymentMethodId": 1, "paymentMethodProductId": null, "displayName": "VISA", "group": { "key": "card", "displayName": "Kredit‐/betalkort" }, "interestRate": null, "notificationFee": null, "setupFee": null,

"numberOfInstallments": null, "installmentPeriod": null, "installmentUnit": null, "legalDocuments": null, "addressTypeRestrictions": [ ] }, { "paymentMethodId": 2, "paymentMethodProductId": null, "displayName": "MasterCard", "group": { "key": "card", "displayName": "Kredit‐/betalkort" }, "interestRate": null, "notificationFee": null, "setupFee": null, "numberOfInstallments": null, "installmentPeriod": null, "installmentUnit": null, "legalDocuments": null, "addressTypeRestrictions": [ ] }, { "paymentMethodId": 311, "paymentMethodProductId": "DirectInvoice", "displayName": "Faktura", "group": { "key": "invoice", "displayName": "Faktura" }, "interestRate": { "label": null, "symbol": "%", "value": "0"

}, "notificationFee": { "label": null, "symbol": "kr", "value": "0" }, "setupFee": { "label": null, "symbol": "kr", "value": "0.000" }, "numberOfInstallments": null, "installmentPeriod": null, "installmentUnit": null, "legalDocuments": [ { "label": "Avtalsvillkor faktura", "uri": "http://www.paynova.com" } ], "addressTypeRestrictions": [ ] }, { "paymentMethodId": 311, "paymentMethodProductId": "InstallmentsSixMonths", "displayName": "Avbetalning 6 månader", "group": { "key": "installment", "displayName": "Delbetalning" }, "interestRate": { "label": null, "symbol": "%", "value": "0" },

"notificationFee": { "label": null, "symbol": "kr", "value": "0" }, "setupFee": { "label": null, "symbol": "kr", "value": "0.000" }, "numberOfInstallments": 6, "installmentPeriod": 1, "installmentUnit": "month", "legalDocuments": [ { "label": "Avtalsvillkor faktura", "uri": "http://www.paynova.com" } ], "addressTypeRestrictions": [ ] }, { "paymentMethodId": 311, "paymentMethodProductId": "InstallmentsTwelveMonths", "displayName": "Avbetalning 12 månader", "group": { "key": "installment", "displayName": "Delbetalning" }, "interestRate": { "label": null, "symbol": "%", "value": "0" }, "notificationFee": {

"label": null, "symbol": "kr", "value": "0" }, "setupFee": { "label": null, "symbol": "kr", "value": "0.000" }, "numberOfInstallments": 12, "installmentPeriod": 1, "installmentUnit": "month", "legalDocuments": [ { "label": "Avtalsvillkor faktura", "uri": "http://www.paynova.com" } ], "addressTypeRestrictions": [ ] }, { "paymentMethodId": 308, "paymentMethodProductId": null, "displayName": "MasterPass", "group": { "key": "other", "displayName": "Other" }, "interestRate": null, "notificationFee": null, "setupFee": null, "numberOfInstallments": null, "installmentPeriod": null, "installmentUnit": null, "legalDocuments": null,

"addressTypeRestrictions": [ ] } ] }

Create Order POST orders/create/{orderNumber}/{totalAmount}/{currencyCode}

The next step is to create an order in Paynova's system.

This is the same Create Order API call that is used for Paynova other payment methods. See the full documentation at:

http://docs.paynova.com/display/API/Create+Order

Example request POST orders/create/{orderNumber}/{totalAmount}/{currencyCode}

{     "orderNumber": "test‐1234567‐1",     "currencyCode": "SEK",     "totalAmount": "125",     "customer": {         "customerId": "",         "governmentId": "198901157993",         "emailAddress": "[email protected]",         "name": {             "companyName": "",             "firstName": "NAMNI",             "lastName": "ENAMNI"         },         "homeTelephone": "",

        "workTelephone": "",         "mobileTelephone": ""     },     "billTo": {         "name": {             "companyName": "",             "firstName": "",             "lastName": ""         },         "address": {             "street1": "GATUADRESS 77",             "street2": "",             "street3": "",             "street4": "",             "city": "LANDSKRONA",             "postalCode": "26151",             "regionCode": "",             "countryCode": "SE"         }     },     "shipTo": {         "name": {             "companyName": "",             "firstName": "",             "lastName": ""         },         "address": {             "street1": "",             "street2": "",             "street3": "",             "street4": "",             "city": "",             "postalCode": "",             "regionCode": "",             "countryCode": ""

        }     },     "lineItems": [{         "id": 1,         "articleNumber": "277",         "name": "Testprodukt 25%",         "description": "Testprodukt 25%",         "productUrl": "http://www.google.se",         "quantity": "1",         "unitMeasure": "st",         "unitAmountExcludingTax": "100",         "taxPercent": "25",         "totalLineTaxAmount": "25",         "totalLineAmount": "125"     }],     "orderDescription": "",     "salesChannel": "",     "salesLocationId": "" }

Example response { "status": { "isSuccess": true, "errorNumber": 0, "statusKey": "SUCCESS", "statusMessage": "The operation was successful.", "errors": null, "exceptionDetails": null }, "orderId": "b539dc60‐3f6e‐407f‐a47a‐a43700eec8c2" }

Authorize Payment POST /orders/{orderId}/authorizePayment

Once the order has been created in Paynova's system an authorization request is sent to Paynova. Paynova will perform the necessary KYC (know your customer), fraud and credit checks and respond with a transaction status (OK, Declined) and the transaction details.

In a typical checkout flow the authorization request should be sent immediately after the order has been created.

Example request POST /orders/aa681dad‐292d‐49e8‐870b‐a41f00fb0755/authorizePayment

{   "AuthorizationType": "InvoicePayment",   "TotalAmount": 125.00,   "PaymentMethodId": 311,   "PaymentMethodProductId": "DirectInvoice",   "PaymentChannelId": 1 }

Example response { "status": { "isSuccess": true, "errorNumber": 0, "statusKey": "SUCCESS", "statusMessage": "The operation was successful.", "errors": null, "exceptionDetails": null

}, "orderId": "aa681dad‐292d‐49e8‐870b‐a41f00fb0755", "transactionId": "201502090957016672" }

Finalize Authorization POST /orders/{OrderId}/transactions/{transactionId}/finalize/{totalAmount}

When the order has been shipped to the customer it can be finalized in Paynova's system. This means that Paynova will create and send out the invoice and initiate the payment collection process.

More information on the Finalize Authorization call can be found here:

http://docs.paynova.com/display/API/Finalize+Authorization

Example request POST /orders/aa681dad‐292d‐49e8‐870b‐a41f00fb0755/transactions/20150209095 7016672/finalize/125

Example response { "status": { "isSuccess": true, "errorNumber": 0, "statusKey": "SUCCESS", "statusMessage": "The operation was successful.", "errors": null, "exceptionDetails": null },

"totalAmountFinalized": "125", "totalAmountPendingFinalization": "0", "canFinalizeAgain": false, "amountRemainingForFinalization": "0", "transactionId": "201502090957016672", "batchId": null, "acquirerId": "1045" }