API Ref Initializepayment

POST /CheckOut2Api/InitializePayment

Passes information about an order from the partner site to the service and negotiates a new session. For usage notes, see Session Negotiation.

In this method, the partner site has an option to provide various information about the customer that can be pre-filled into the form once shown. Based on further business logic, the customer may or may not be allowed to change some of these values.

Input Parameters

Name	Data Type	Default Value	Description
Description	String (max. 4000 characters)	An empty string	A textual description of the purchase without any specific format that the partner may provide.
Phone	String (max. 15 characters not counting white spaces, so technically any length)	An empty string	Customer’s phone number to pre-fill in the form.
Mail	String (max. 60 characters)	An empty string	Customer’s e-mail address to pre-fill in the form.
IsPhoneAndMailEditable	Boolean	true	Whether to allow the user to edit the Phone and Mail fields.
Price	Decimal	None. Must be specified	The total amount to pay. Must be greater than 0.
Items	Class List of Items	None. Must be specified	A list of items representing the individual rows on an invoice. Individual items may have a negative value but the total sum of all items must be positive.
InvoicingFirstName	String (max. 40 characters)	An empty string	Customer’s first name. This is used also as a first name of the person on the invoicing address.
InvoicingLastName	String (max. 40 characters)	An empty string	Customer’s last name. This is used also as a last name of the person on the invoicing address.
InvoicingAddressLine1	String (max. 40 characters)	An empty string	The line of the invoicing address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
InvoicingAddressLine2	String (max. 40 characters)	An empty string	The line of the invoicing address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
InvoicingZip	String (max. 6 characters)	An empty string	The ZIP on the invoicing address.
InvoicingCity	String (max. 30 characters)	An empty string	The city on the invoicing address.
IsInvoicingEditable	Boolean	False	Whether the customer can edit the attributes related to invoicing address manually.
DeliveryFirstName	String (max. 40 characters)	An empty string	First name of the person on the delivery address.
DeliveryLastName	String (max. 40 characters)	An empty string	Last name of the person on the delivery address.
DeliveryAddressLine1	String (max. 50 characters)	An empty string	First line of the delivery address.
DeliveryAddressLine2	String (max. 50 characters)	An empty string	Second line of the delivery address.
DeliveryZip	String (max. 6 characters)	An empty string	The ZIP on the delivery address.
DeliveryCity	String (max. 30 characters)	An empty string	The city on the delivery address.
IsDeliveryEditable	Boolean	False	Enabling/disabling checkbox visibility for delivery address.
UseDifferentDeliveryAddress	Boolean	False	The initial state of the “Same delivery address” checkbox on the check-out form.
UserLanguageCode	String	en-US	The culture to use in check-out form. Affects both language and value formatting. Supported values: en-US: English sv-SE: Swedish fi-FI: Finnish da-DK: Danish nb-NO: Norwegian
ProductGroup	String	An empty string	String that defines the product category.
LoyaltyNumber	String	An empty string	Can be a number of a customer’s membership card.
OrderReference	String	An empty string	Merchant custom ID reference.
ReleasedByName	String	An empty string	Sales Representative.
DefaultPaymentMethod	Enumeration PaymentMethod	Invoice	A payment method to pre-select when the check-out form is shown for the first time.
PreSelectRecPmt	Boolean	false
OfferRecPmt	Boolean	false
HideCustomerDetails	Boolean	false	Feature which allows hide customer details.
CompanyName	String	An empty string	Allows to send company name in request.
CustomerToken	String	An empty value	CustomerToken is a key associated with customer details.
EmailInvoice	Nullable int	null	0 = Do not send ivoice by email. 1 = Send invoice by email. empty = no update.
OfferNewsLetter	Boolean	false	OfferNewsLetter in combination with EnableNewsletter, both set true, displays the newsletter option.
PreSelectNewsLetter	Boolean	True	If the checkbox “OfferNewsLetter” should be selected or not.
OfferNewsLetterSMS	Boolean	false	OfferNewsLetterSMS in combination with EnableNewsletter, both set true, displays the newsletter option.
PreSelectNewsLetterSMS	Boolean	True	If the checkbox “OfferNewsLetterSMS” should be selected or not.
DisableFocus	Boolean	false	Focus which appears in email, zip and ssn textboxes will be disabled.
OrganizationNumber	String	An empty string	Number for organizations.
CustomerType	Enum	0	If CustomerType = null or 0 load both options for Private/Company. If CustomerType = 1 load only Private alternative. If CustomerType = 2 load only Company alternative.
TermsAndConditionsUrl	String	An empty string	Add new terms & conditions to checkout footer.
Attachment	String	null	Any custom data to be attached to the purchase.
SSN	string	null	SSN can be prefilled in Checkout if submitted. example FI: 080286-073A example SE: 197901121181
PosID	string	null	StoreID – optional parameter to indicate which store this order/authorization is associated to.

Items

The class represents a single row that appears on an invoice. Typically a purchased commodity but it can also be a more abstract think such as a discount with a negative value.

Property	Data Type	Default Value	Description
Description	String (max. 35 characters)	None. Must be specified.	A shorter description of the item (that would typically appear on an invoice line)
Notes	String (max. 35 characters)	An empty string	An optional longer description of the item that might or might not be displayed on the invoice.
Amount	Decimal	None. Must be specified.	The item amount. Can be negative, zero or positive. The tax amount should be included in the amount.
TaxCode	String	An empty string.	The tax code. The value should be in %. If tax code are 25% send in 25.
TaxAmount	Decimal	0.00	The item tax amount. Can be zero or positive.
ProductGroup	String (max. 50 characters)	None.	An optional product group.

Example request

{
  "Mail": "Customers@mail.adddress",
  "Description": "New standard purchase",
  "Price": 100,
  "Items": [
    {
      "Amount": 90,
      "Description": "quitar"
    },
    {
      "Amount": 10,
      "Description": "piano"
    }
  ]
}

Return value

The method returns a Purchase ID for the negotiated session formatted as a string. An example:

"19ac0d1ee909c302d212b4324d9194b5"

Please note that although the return type is just a simple string, it is still formatted as JSON. Hence the quotes.

Error messages

Error message
Address (in delivery address) must be between 0 and 40 characters.
Address (in invoicing address) must be between 0 and 40 characters.
Address (in invoicing address) should not be empty.
Amount can’t be empty!
Checkout site is not allowed to work with B2b.
City (in delivery address) must be between 0 and 30 characters.
City (in invoicing address) must be between 0 and 30 characters.
City (in invoicing address) should not be empty.
Customer Token is not valid.
Description must be between 0 and 4000 characters.
E-mail is not a valid email address.
E-mail must be between 0 and 60 characters.
E-mail should not be empty.
EmailInvoice must be equal 0, 1 or empty
Identification Number should not be empty.
Invalid or not supported UserLanguageCode.
Item Amount must be specified.
Item description must be specified and must not be longer than 35 characters or empty.
Item notes must not be longer than 35 characters.
Items List must contain at least one item.
Name (in delivery address) must be between 0 and 40 characters.
Name (in invoicing address) must be between 0 and 100 characters.
Name (in invoicing address) must be between 0 and 40 characters.
Name (in invoicing address) should not be empty.
Number of notes characters exceeded
Order Reference should not be empty.
Payment Terms should not be empty.
Phone Number must be between 0 and 15 characters.
Phone should not be empty.
Price must be either 0 (in case of no items), or greater than or equal to 0 and greater than or equal to sum of item prices.
Price should not be empty.
Site has no invoice account class associated.
SSN is invalid.
TermsAndConditionsUrl is not in valid format
The items amount can have a maximum of 2 decimal places.
The items tax amount can have a maximum of 2 decimal places.
The payment term is invalid.
The price can have a maximum of 2 decimal places.
Total price is not equal to sum of item prices
ZIP (in delivery address) must be between 0 and 10 characters.
ZIP (in invoicing address) must be between 0 and 10 characters.
ZIP (in invoicing address) should not be empty.

API Reference GetPaymentStatus