INTEGRATION DOCUMENTATION Svea Checkout API v1.12

Transcription

1 INTEGRATION DOCUMENTATION Svea Checkout API v1.12

2 2 (18) Svea Checkout API Change history: v1.12 Updated list of Payment methods v1.11 Updated properties names for CheckoutValidationCallback Renamed OrderStockStatusResponse to CheckoutValidationCallbackResponse v1.10 Added MerchantSetting CheckoutValidationCallBackUri Added OrderStockStatusResponse v1.09 Added MerchantSetting PreferedPartPaymentCampaign Added MerchantSetting ActivePartPaymentCampaigns Added Endpoint util/getavailablepartpayments v1.08 Updated list of available observable properties v1.07 Updated description for DiscountPercentage v1.06 Added payment type ADMININVOICE v1.05 Added SveaWillBuyOrder to Data object v1.04 Security clarifications for merchant settings v1.03 Added CustomerReference to Order object v1.02 Clarifications v1.01 Authentication examples v1.0 Release version

3 3 (18) Svea Checkout API Disclaimer This documentation is subject to continuous updates. Please make sure you are using the latest version. Contact with questions regarding this documentation.

4 4 (18) Svea Checkout API Content Change history:... 2 Introduction... 6 When should you send the order to your customer?... 6 Testing... 6 Production... 6 Firewall... 6 Authentication... 7 GET-Request example:... 7 POST-Request example:... 7 Checkout API... 9 Create... 9 Get... 9 Update GetAvailablePartPaymentCampaigns Data objects Data CampaignCodeInfo List of Payment Plan Types MerchantSettings Cart OrderRow Gui Customer Address HttpStatusCodes in use PresetValue List of presetvalue typenames CheckoutOrderStatus Locale PaymentType Direktbank-type Example calls Create Update order rows... 17

5 5 (18) Svea Checkout API JavaScript API (preview) API entry point Listening for API readiness Available operations... 18

6 6 (18) Svea Checkout API Introduction All URI:s are written in the specific form: URI: ActualURI [HTTP-VERB] Example: Get order by id 1: URI: [GET] A star in the column indicates: RO represents Read only, data that is only used in output. R represents Required, the request is not valid unless this data is included. All amounts are written in their minor currency. Example: SEK will be written as 1525, 120 SEK will be written as etc. All URI s are specified with each documented call below. All data sent to the system should be correctly UTF-8 encoded. When should you send the order to your customer? The order is ready to send to customer when the checkoutorderstatus is Final. Testing External test address: Production External prod address: Firewall When we need to inform you that an order is updated then our server will try to call your server through the pushuri-string that you provide in the MerchantSettings-object when you call CreateOrder. Make sure that your server accepts calls to the pushuri and that your firewall whitelists connections from our IP-range: /24 Payload The payload is always in JSON format.

7 7 (18) Svea Checkout API Authentication Every request to the API must be authenticated by using the Authorization HTTP requestheader. The utctimestamp should be in the header, named timestamp and the value should be the time in UTC when the message was sent. The authorization header is calculated for each request using this formula: base64 (utf8 ({checkoutmerchantid}: base16 (lowercase (sha512 (utf8({request body }{checkoutsecret}{utctimestamp})))))) Where {checkoutmerchantid} is the merchant identifier assigned to you by Svea, formatted as {request_body} is the body of the request, or an empty string for GET requests {checkoutsecret} is the secret key assigned to your CheckoutMerchantId by Svea {utctimestamp} is the time in UTC the message was created, in the format YYYY- MM-DD HH:MM:SS GET-Request example: CheckoutMerchantId: 1 Timestamp: :40:00 CheckoutSecret: sharedsecret lowercase(sha512(sharedsecret :40:00)) = 1:ec0a.7eb5 base64(1:ec0a.7eb5) = MTpl. NQ== Authorization header final value: Svea = MTplYzBhZDQ2NTI2YTRiOGM1OTc5YzNjN2FiMWViNTk4NTRiODU3YzhkNWVlNDUwZWRm YWQyMzNmNzliZDcxNzcxMDgzNDBmMzA1OGExMzZkNzgxZDU2MDYyZGQwZWIxZWMyZm FiNzcyZDI5NWMzZGE3MmEzMTZjYWM2MGFhN2ViNQ== POST-Request example: CheckoutMerchantId: CheckoutSecret: sharedsecret Timestamp: :39:00 Request_body: {"MerchantSettings":{"TermsUri":" op.se/checkout","confirmationuri":" ps://svea.com/push.aspx?sid=123&svea_order={checkout.order.uri}"},"cart":{"items":[{ "ArticleNumber":" ","Name":"Computer","Quantity":200,"UnitPrice":12300,"Disc ountpercent":1000,"vatpercent":2500},{"articlenumber":"ship.","name":"shipping Fee","Quantity":100,"UnitPrice":4900,"VatPercent":2500}]},"Locale":"sv- SE","CountryCode":"SE","Currency":"SEK", "ClientOrderNumber":"54234"} lowercase(sha512({"merch 54234"}sharedSecret :39:00)) = 4ad2.6208

8 8 (18) Svea Checkout API base64(123123:4ad2.6208) = MTIz.MjA4 Authorization header final value: Svea = MTIzMTIzOjRhZDJmYjg0MTA1ODU3ZDMwYTZiMzg1MTVkYzJlZTAxZGQ2OWFkO WUwZDk3MGFmYWQwNDg2OThiOGFmZmE1OWJkN2MzZTEwMmUyYWM2ZGFh NDNhOWZkNzYwOTFjMmFiNDE5N2RhZmFjMTgwYzZkMzQ1N2Y0ZWNiYTBiNGU2 MjA4

9 9 (18) Svea Checkout API Checkout API Create Creates a new order and returns the checkout to the webshop. URI: /api/orders/ [POST] Parameters IN: Parameter Required Type Description MerchantSettings * MerchantSettings The merchants settings for the order. Cart * Cart A cart-object containing the orderrows. Locale * String The current locale of the checkout, i.e. sv-se etc. Currency * String The current currency as defined by ISO 4217, i.e. SEK, NOK etc. CountryCode * String Defined by two-letter ISO alpha-2, i.e. SE, DE, FI etc. ClientOrderNumber * String A string with maximum of 32 characters identifying the order in the merchant s system. PresetValues Array of PresetValue Values chosen by the merchant to be prefilled and eventually locked for changing by the customer. Parameters OUT: Data Data An object containing all information needed to return a checkout to the merchant, see structure below. HTTP status code 201 indicating success, everything else indicates a failure. Get Returns a datastructure containing seven parameters that contains all information about the order and what is needed for the GUI. URI: /api/orders/{orderid} [GET] Parameters IN: Parameter Required Type Description Id * Long Checkoutorderid of the specified order. Parameters OUT: Data Data An object containing all information needed to return a checkout to the merchant, see structure below. HTTP status code 200 indicating success, everything else indicating a failure.

10 10 (18) Svea Checkout API Update Replaces the order rows of the specified order with the new appended in the call. URI: /api/orders/{orderid} [PUT] Parameters IN as URI-parameters: Parameter Required Type Description Id * Long Checkoutorderid of the specified order. Parameters IN as content: Parameter Required Type Description Cart * Cart Contains the orderrows that will be set to the specified order. Parameters OUT: Data Data An object containing all information needed to return a checkout to the merchant, see structure below. HTTP status code 200 indicating success, everything else indicating a failure. GetAvailablePartPaymentCampaigns Returns a list of available B2C/B2B part payment campaigns URI: /api/util/getavailablepartpaymentcampaigns [GET] Parameters IN: Parameter Required Type Description IsCompany * Boolean True for B2B, false for B2C Parameters OUT: Data Array of CampaignCodeInfo A list of campaigns. HTTP status code 200 indicating success, everything else indicates a failure.

11 11 (18) Svea Checkout API Data objects Data MerchantSettings MerchantSettings Specific merchant URIs, see structure below. Cart Cart Order rows. Gui Gui See structure below. Customer Customer Identified customer of the order. ShippingAddress Address Shipping address of identified customer. BillingAddress Address Billing address of identified customer. CustomerReference String B2B Customer reference Locale String The current locale of the checkout, i.e. sv-se etc. Currency String The current currency as defined by ISO 4217, i.e. SEK, NOK etc. CountryCode String Defined by two-letter ISO alpha-2, i.e. SE, DE, FI etc. ClientOrderNumber String A string with maximum of 32 characters that identifies the order in the merchant s systems. PresetValues Array of PresetValue A list containing the preset values, if any. See structure below. OrderId Long Checkoutorderid of the order. Status CheckoutOrder- Status The current state of the order, see structure below. Address String The customer s address PhoneNumber String The customer s phone number PaymentType String The final payment method for the order. Will only have a value when the order is locked, otherwise null. SveaWillBuyOrder Nullable boolean True = Svea will buy this invoice. False = Svea will not buy this invoice. null = Selected payment method is not Invoice. CampaignCodeInfo CampaignCode Integer CampaignId ContractLengthInMonths Integer Contract length in months Description String Campaign description FromAmount Decimal Minimum amount (major currency) ToAmount Decimal Maximum amount (major currency) InitialFee Decimal Initial fee (major currency) InterestRatePercent Decimal Interest rate in percent (e.g. 40 = 40%) MonthlyAnnuityFactor Decimal Monthly annuity factor NotificationFee Decimal Notification fee (major currency) NumberOfInterestFreeMonths Integer Number of interest free months NumberOfPaymentFreeMonths Integer Number of payment free months PaymentPlanType String Name of the payment plan type (see list below) ToAmount Decimal Maximum cart sum (major currency) List of Payment Plan Types Parameter Standard InterestFree InterestAndAmortizationFree

12 12 (18) Svea Checkout API MerchantSettings Parameter R Type Description Limits TermsUri * String URI to a page with webshop specific terms characters, must be a valid Url CheckoutUri * String URI to the page in the webshop displaying the Checkout. May not contain orderspecifik information. ConfirmationUri * String URI to the page in the webshop displaying specific information to a customer after the order has been confirmed. May not contain orderspecifik information. PushUri * String URl to a location that is expecting callbacks from the Checkout whenever an order s state is changed(confirmed, final, etc.). Uri may have a {checkout.order.uri} placeholder which will be replaced with the checkoutorderid. CheckoutValidationCallBackUri String An optional URl to a location that is expecting callbacks from the Checkout to validate order s stock status, and also the possibility to update checkout with an updated ClientOrderNumber. Uri may have a {checkout.order.uri} placeholder which will be replaced with the checkoutorderid. Please refer below CheckoutValidationCallbackResponse to see the expected response. ActivePartPaymentCampaigns List<Integer> List of valid CampaignIDs. If used then list of available part payment campaign options will be filtered through the chosen list. PromotedPartPaymentCampaign Integer Valid CampaignID. If used then the chosen campaign will be shown as the first payment method in all payment method lists characters, must be a valid Url characters, must be a valid Url characters, must be a valid Url characters, must be a valid Url Must be a list of valid CampaignIDs Must be valid CampaignID CheckoutValidationCallbackResponse Parameter Required Type Description Valid * bool A value of true/false specifying if the items in the cart are in stock or not. ClientOrderNumber string This is an optional property which can be used to notify checkout that the ClientOrderNumber has been updated. Cart Parameter Required Type Description Items * List of OrderRow See structure below. OrderRow Parameter Required Type Description Limits

13 13 (18) Svea Checkout API ArticleNumber String Articlenumber as a string, can contain letters and numbers. Maximum 256 characters. Name * String Article name characters. Quantity * Integer Quantity of the product. 1-9 digits. Minor currency. UnitPrice * Integer Price of the product including VAT digits, can be negative. Minor currency. DiscountPercent Integer The discountpercent of the product No fractions. 0 = 0% 100 = 1% 1000 = 10% 9900 = 99% VatPercent * Integer The VAT percentage of the current product. Unit String The unit type, e.g., st, pc, kg etc. TemporaryReference String Can be used when creating or updating an order. The returned rows will have their corresponding temporaryreference as they were given in the indata. it will not be stored and will not be returned in GetOrder. RowNumber Integer The row number the row will have in the Webpay system Valid vat percentage for that country. Minor currency. 0-4 characters. Gui Layout String Defines the orientation of the device, either desktop or portrait. Snippet String HTML-snippet including javascript to populate the iframe. Customer NationalId String Personal- or organizationnumber. IsCompany Boolean True if nationalid is organisationnumber, false if nationalid is personalnumber. IsMale Boolean Indicating if the customer is male or not. DateOfBirth DateTime Required only for DE and NL or if NationalId is not set for any reason. Address FullName String Company: name of the company. Individual: first, middle and last name(s). FirstName String First name(s). LastName String Last name(s). StreetAddress String Street address. CoAddress String Co address. PostalCode String Postal code. City String City. CountryCode String Defined by two-letter ISO alpha-2, i.e. SE, DE, FI etc.

14 14 (18) Svea Checkout API HttpStatusCodes in use 200 Success Request was successful. 201 Created The order was created successfully. 302 Found The order was found. 400 Bad Request The input data was invalid. 401 Unauthorized The request did not contain correct authorization. 403 Forbidden The request did not contain correct authorization. 404 Not Found No order with the requested ID was found. PresetValue Parameter Required Type Description TypeName * String Name of the field you want to set (see list below). Value * String See limits below. IsReadOnly * Boolean Should the preset value be locked for editing, set readonly to true. Usable if you only let your registered users use the checkout. List of presetvalue typenames Parameter Type Limits NationalId String Company specific validation. Address String Max 50 characters, will be validated as an address. PhoneNumber String 1-18 digits, can include +, - s and space. PostalCode String Company specific validation. IsCompany Boolean Required if nationalid is set. CheckoutOrderStatus Parameter Cancelled Created Confirmed PaymentGuaranteed WaitingToBeSent Final Locale Parameter sv-se PaymentType Name Null INVOICE ADMININVOICE PAYMENTPLAN SVEACARDPAY SVEACARDPAY_PF Direktbank-type ACCOUNTCREDIT Description The order has been cancelled due to inactivity. The order has been created. The order has been confirmed using card payment and is waiting to be paid by the customer. The order has been confirmed using a credit option; invoice, paymentplan or accountcredit. The order is finished and is waiting to be sent to WebPay s subsystems for further handling. The order is completed in the checkout and managed by WebPay s subsystems. Description Swedish locale. Description The customer havn t confirmed the order or can still change paymenttype. The customer chose Invoice The customer chose Invoice that Svea won t buy. The customer chose a payment plan The customer paid the order with card The customer paid the order with card using Svea s Payment facilitator. A value from the direktbank list below. The customer paid the order with direct bank e.g. Nordea, SEB. For the most recent list of available banks check the Payment Gateway documentation. The customer chose to use their account credit.

15 15 (18) Svea Checkout API Direktbank-type Parameter BANKAXESS DBAKTIAFI DBALANDSBANKENFI DBDANSKEBANKSE DBNORDEAFI DBNORDEASE DBPOHJOLAFI DBSAMPOFI DBSEBSE DBSEBFTGSE DBSHBSE DBSPANKKIFI DBSWEDBANKSE DBTAPIOLAFI Description BankAxess, Norway Aktia, Finland Ålandsbanken, Finland Danske bank, Sweden Nordea, Finland Nordea, Sweden OP-Pohjola, Finland Sampo, Finland SEB, Individuals, Sweden SEB, companies, Sweden Handelsbanken, Sweden S-Pankki, Finland Swedbank, Sweden Tapiola, Finland

16 16 (18) Svea Checkout API Example calls Create One important thing to note here is that Quantity, UnitPrice, DiscountPercent and VatPercent for each order row is expected to be given in minor currency. In this example we add two items, one called Computer with a price of SEK, a discount of 10% and 25% VAT, and another related to the shipping fee. These values should be added as price: , quantity: 100, discountpercent: 1000 and vatpercent: Uri: /api/orders/ HttpAction: Post Headers: Timestamp: :44 HttpContent: { "MerchantSettings": { "TermsUri": " "CheckoutUri": " "ConfirmationUri": " "PushUri": " "CheckoutValidationCallBackUri": " }, "Cart": {"Items": [ { "ArticleNumber": "4315", "Name": "Computer", "Quantity": 100, "UnitPrice": , "DiscountPercent": 1000, "VatPercent": 2500 }, { "ArticleNumber": "SHIPPING", Name": "Shipping Fee", "Quantity": 100, "UnitPrice": 4900, "VatPercent": 2500 } ]}, "Locale": "sv-se", "CountryCode": "SE", "Currency": "SEK", ClientOrderNumber : , Timestamp : :01:01 } You can optionally add presetvalues to the call as well. These values will prefill the identification in the checkout. If a preset value has IsReadOnly, the customer will not be able to modify the value. "PresetValues":[ {"TypeName":" address","Value":"test@sveaekonomi.se","IsReadOnly":true}, {"TypeName":"ZipCode","Value":"49763"," IsReadOnly ":true}

17 17 (18) Svea Checkout API ] Update order rows Updates the orderrows for the current checkoutorderid passed as parameter in the URI. The order rows of the order will be substituted with the order rows that is being sent in with this call. That means, should a customer change the quantity for one of five order rows, all five of the order rows must be passed again with the updated values. Uri: /api/orders/{id} HttpAction: Put HttpContent: { "Cart": {"Items": [ { "ArticleNumber": " ", Name": "Computer 2.0", "Quantity": 100, "UnitPrice": , "DiscountPercent": 1000, "VatPercent": 2500 }, { "ArticleNumber": "SHIPPING", "Name": "Shipping Fee", "Quantity": 100, "UnitPrice": 4900, "VatPercent": 2500 } ]} }

18 18 (18) Svea Checkout API JavaScript API (preview) Starting with release , merchants can now use the Checkout JavaScript API to access data and functionality previously internal to the checkout. For the time being, this primarily concerns reloading payment methods and observing changes in the state and data model. Please note that the API is still considered a work in progress and might see significant changes in the coming few releases. API entry point window.scoapi is the root object for the API and contains all the operations available. Listening for API readiness The checkout raises an event when ready, which can be used to safely access the API. Example: document.addeventlistener("checkoutready", function() { window.scoapi... // Your code here }); Available operations observemodel(propertystring, handlerfunction) => function Observes the client data property for changes, calling the supplied function when a change is detected. Note that the underlying value must change and pass validation to trigger the handler. Returns a function that can be called to stop observing the specified property. The following properties are currently supported: "identity.iscompany" "identity. " "identity.postalcode" "identity.phonenumber" "identity.city" "identity.organisationnumber" "identity.nationalidnumber" "identity.companyname" "identity.firstname" "identity.lastname" "identity.streetaddress" "identity.coaddress" Example: // Observe the city property var observer = window.scoapi.observemodel( "identity.city", function (data) { console.log("city changed to %s.", data.value); }); // Stop observing observer(); setcheckoutenabled(value) => void Pass a false-ish value to disable the checkout. While disabled, the merchant can safely perform updates to the cart. When finished, call setcheckoutenabled(true) to re-enable the checkout and make it reflect the changes made.