Created with Sketch.
Created with Sketch.
Checkout 2.0

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

NameData TypeDefault ValueDescription
DescriptionString (max. 4000 characters)An empty stringA textual description of the purchase without any specific format that the partner may provide.
PhoneString (max. 15 characters not counting white spaces, so technically any length)An empty stringCustomer’s phone number to pre-fill in the form.
MailString (max. 60 characters)An empty stringCustomer’s e-mail address to pre-fill in the form.
IsPhoneAndMailEditableBooleantrueWhether to allow the user to edit the Phone and Mail fields.
PriceDecimalNone. Must be specifiedThe total amount to pay. Must be greater than 0.
ItemsClass List of ItemsNone. Must be specifiedA 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.
InvoicingFirstNameString (max. 40 characters)An empty stringCustomer’s first name. This is used also as a first name of the person on the invoicing address.
InvoicingLastNameString (max. 40 characters)An empty stringCustomer’s last name. This is used also as a last name of the person on the invoicing address.
InvoicingAddressLine1String (max. 40 characters)An empty stringThe line of the invoicing address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
InvoicingAddressLine2String (max. 40 characters)An empty stringThe line of the invoicing address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
InvoicingZipString (max. 6 characters)An empty stringThe ZIP on the invoicing address.
InvoicingCityString (max. 30 characters)An empty stringThe city on the invoicing address.
IsInvoicingEditableBooleanFalseWhether the customer can edit the attributes related to invoicing address manually.
DeliveryFirstNameString (max. 40 characters)An empty stringFirst name of the person on the delivery address.
DeliveryLastNameString (max. 40 characters)An empty stringLast name of the person on the delivery address.
DeliveryAddressLine1String (max. 50 characters)An empty stringFirst line of the delivery address.
DeliveryAddressLine2String (max. 50 characters)An empty stringSecond line of the delivery address.
DeliveryZipString (max. 6 characters)An empty stringThe ZIP on the delivery address.
DeliveryCityString (max. 30 characters)An empty stringThe city on the delivery address.
IsDeliveryEditableBooleanFalseEnabling/disabling checkbox visibility for delivery address.
UseDifferentDeliveryAddressBooleanFalseThe initial state of the “Same delivery address” checkbox on the check-out form.
UserLanguageCodeStringen-USThe 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
ProductGroupStringAn empty stringString that defines the product category.
LoyaltyNumberStringAn empty stringCan be a number of a customer’s membership card.
OrderReferenceStringAn empty stringMerchant custom ID reference.
ReleasedByNameStringAn empty stringSales Representative.
DefaultPaymentMethodEnumeration PaymentMethodInvoiceA payment method to pre-select when the check-out form is shown for the first time.
PreSelectRecPmtBooleanfalse 
OfferRecPmtBooleanfalse 
HideCustomerDetailsBooleanfalseFeature which allows hide customer details.
CompanyNameStringAn empty stringAllows to send company name in request.
CustomerTokenStringAn empty valueCustomerToken is a key associated with customer details.
EmailInvoiceNullable intnull0 = Do not send ivoice by email.

 

1 = Send invoice by email.

empty = no update.

OfferNewsLetterBooleanfalseOfferNewsLetter in combination with EnableNewsletter, both set true, displays the newsletter option.
PreSelectNewsLetterBooleanTrueIf the checkbox “OfferNewsLetter” should be selected or not.
OfferNewsLetterSMSBooleanfalseOfferNewsLetterSMS in combination with EnableNewsletter, both set true, displays the newsletter option.
PreSelectNewsLetterSMS BooleanTrueIf the checkbox “OfferNewsLetterSMS” should be selected or not.
DisableFocusBooleanfalseFocus which appears in email, zip and ssn textboxes will be disabled.
OrganizationNumberStringAn empty stringNumber for organizations.
CustomerTypeEnum0If CustomerType = null or 0 load both options for Private/Company.
If CustomerType = 1 load only Private alternative.
If CustomerType = 2 load only Company alternative.
TermsAndConditionsUrlStringAn empty stringAdd new terms & conditions to checkout footer.
AttachmentStringnullAny custom data to be attached to the purchase.
SSNstringnullSSN can be prefilled in Checkout if submitted.
example FI: 080286-073A
example SE: 197901121181

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.

PropertyData TypeDefault ValueDescription
DescriptionString (max. 35 characters)None. Must be specified.A shorter description of the item (that would typically appear on an invoice line)
NotesString (max. 35 characters)An empty stringAn optional longer description of the item that might or might not be displayed on the invoice.
AmountDecimalNone. Must be specified.The item amount. Can be negative, zero or positive. The tax amount should be included in the amount.
TaxCodeStringAn empty string.The tax code. The value should be in %. If tax code are 25% send in 25.
TaxAmountDecimal0.00The item tax amount. Can be zero or positive.
ProductGroupString (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

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.