Created with Sketch.
Created with Sketch.
Checkout 3.0

Confirmation

On this page you will find information about how to Process the result and the different Purchase states through out the CheckOut session.

Processing the Result

The last step occurs when the customer finishes working with the form and there’s a result available. The client script signals this by calling the done callback function (see Showing the Check-Out Form).

The done callback doesn’t contain any information about whether the payment succeeded or not. It only signals that the customer is done working with the form. The partner site back-end must check what the actual result was. We have designed it this way as a security measure, so that the partner integrators aren’t tempted to trust the client script. Unfortunately, there’s no way to prevent malicious customers from modifying the script since it runs in their browsers.

The implementation of the done function is up to partners. However, a common scenario verifies the result, passing the Purchase ID is a parameter of payment status API funtion

Payment Status

Returns information about a single purchase identified by a Purchase ID.

GET: {api_url}/api/partner/payments/{purchaseid}
Authorization: Bearer {partner_access_token} 

Example:

{
  "purchaseId": "string",
  "extraIdentifiers": {
    "description": "string",
    "orderReference": "string",
    "loyaltyNumber": "string",
    "productGroup": "string",
    "attachment": "string",
    "referenceName": "string"
  },
  "totalPrice": 0,
  "createdUtc": "2020-05-27T10:15:21.195Z",
  "expiredUtc": "2020-05-27T10:15:21.195Z",
  "checkoutSite": {
    "siteCode": "string",
    "countryCode": "string",
    "currencyCode": "string"
  },
  "mode": "B2C",
  "b2C": {
    "step": {
      "customerToken": "string",
      "current": "Initialized",
      "rememberMe": "Hidden",
      "smsNewsletterSubscription": "Hidden",
      "emailNewsletterSubscription": "Hidden"
    },
    "userInputs": {
      "email": "string",
      "zip": "string",
      "ssn": "string",
      "phone": "string"
    },
    "invoicingAddress": {
      "address1": "string",
      "address2": "string",
      "zip": "string",
      "city": "string",
      "country": "AF",
      "careOfAddress": true,
      "firstName": "string",
      "lastName": "string"
    },
    "deliveryAddress": {
      "address1": "string",
      "address2": "string",
      "zip": "string",
      "city": "string",
      "country": "AF",
      "careOfAddress": true,
      "firstName": "string",
      "lastName": "string",
      "type": "Default",
      "viewType": "Unchecked"
    }
  },
  "b2B": {
    "step": {
      "customerToken": "string",
      "current": "Initialized",
      "rememberMe": "Hidden",
      "smsNewsletterSubscription": "Hidden",
      "emailNewsletterSubscription": "Hidden"
    },
    "userInputs": {
      "email": "string",
      "zip": "string",
      "organizationNumber": "string",
      "customerSsn": "string",
      "phone": "string"
    },
    "customerInfo": {
      "firstName": "string",
      "lastName": "string"
    },
    "invoicingAddress": {
      "address1": "string",
      "address2": "string",
      "zip": "string",
      "city": "string",
      "country": "AF",
      "careOfAddress": true,
      "name": "string"
    },
    "deliveryAddress": {
      "address1": "string",
      "address2": "string",
      "zip": "string",
      "city": "string",
      "country": "AF",
      "careOfAddress": true,
      "firstName": "string",
      "lastName": "string",
      "type": "Default",
      "viewType": "Unchecked"
    }
  },
  "authenticationType": "None",
  "paymentMethods": {
    "selectedPayment": {
      "type": "Invoice",
      "recurringPayment": "Hidden",
      "recurringPaymentToken": "string"
    }
  },
  "cardPaymentState": {
    "maskedCardNumber": "string",
    "cardBrand": "string",
    "cardExpirationDate": "string"
  },
  "customerBalance": 0
}

NameData TypeDescription
PurchaseIdstringThe ID that the partner uses to identify the purchase.
ExtraIdentifiersGetPaymentExtraIdentifiersPartner’s identifiers
TotalPricedecimalThe total price that the customer has to pay.
CreatedUtcDateTimeUTC time of purchase creations
ExpiredUtc DateTime UTC time of purchase expiration
CheckoutSiteGetPaymentCheckoutSiteCheckout site information
ModePurchaseModeSelected purchase mode (B2B/B2C)
B2CGetPaymentB2CState
B2BGetPaymentB2BState
CardPaymentState CardState Information about card payment
PaymentMethodsGetPaymentFormPaymentsInformation about Payment methods
AuthenticationTypeAuthenticationTypeType of third party autherntication
CustomerBalancedecimal CustomerBalance

Partner’s purchase identifiers

Name Data Type Description
DescriptionstringAn optional description provided by partner. May be multi-line and may contain whatever the partner want
OrderReferencestring Merchant custom ID reference
LoyaltyNumberstringCan be a number of a customer’s membership card.
ProductGroupstringJust a string that defines the product category. Allow anything for now. Will be defined later.
AttachmentstringRandom merchant’s data (some kind of serialized JSON for example)
ReferenceNamestringMerchant custom value Reference name

Checkout site information

Name Data Type Description
SiteCodestringCode of the site in which the purchase has been made.
CountryCodestringThe three-letters country code of the site.
CurrencyCodestringThe three-letter code of the currency in which the purchase has been made.

B2C State

Name Data Type Description
StepGetPaymentB2CFormStepDescription of current step in checkout flow
UserInputsGetPaymentB2CUserInputsInformation provided by customer in checkout form
InvoicingAddressAddressCustomerInvoicing address
DeliveryAddressDeliveryAddressDelivery address

B2C Step

Name Data Type Description
CustomerTokenstring Customer token
CurrentB2CStepTypeLatest purchase state type
RememberMeCheckBoxStateTypeCheckbox state of remember me
SmsNewsletterSubscriptionCheckBoxStateTypeCheckbox state of sms newsletter subscription
EmailNewsletterSubscriptionCheckBoxStateTypeCheckbox state of email newsletter subscription

Card State

Name Data Type Description
MaskedCardNumberstringIf card payment method was selected, Masked card number used card
CardBrand stringIf card payment method was selected, brand of used card
CardExpirationDate stringIf card payment method was selected, expiration date of used card

B2C User Inputs

Name Data Type Description
EmailstringCustomer’s e-mail address passed by a partner’s application.
ZipstringCustomer’s zip code passed by a partner’s application.
SsnstringCustomer’s social security number
PhonestringCustomer’s phone number passed by a partner’s application.

B2B State

Name Data Type Description
StepGetPaymentB2BFormStepDescription of current step in checkout flow
UserInputsGetPaymentB2BUserInputsInformation provided by customer in checkout form
CustomerInfoGetPaymentB2BCustomerInfoInformation about referer of B2B payment
InvoicingAddressAddressCompanyInvoicing address
DeliveryAddressDeliveryAddressDelivery address

B2B Step

Name Data Type Description
CustomerTokenstring Customer token
CurrentB2BStepTypeLatest purchase state type
RememberMeCheckBoxStateTypeCheckbox state of remember me
SmsNewsletterSubscriptionCheckBoxStateTypeCheckbox state of sms newsletter subscription
EmailNewsletterSubscriptionCheckBoxStateTypeCheckbox state of email newsletter subscription

B2B User inputs

Name Data Type Description
EmailstringCustomer’s e-mail address passed by a partner’s application.
ZipstringCustomer’s zip code passed by a partner’s application.
CompanySsnstringCompany social security number
CustomerSsn string Referrer’s social security number
PhonestringCustomer’s phone number passed by a partner’s application.

B2B Customer Info

Name Data Type Description
FirstNamestringReferrer’s First name.
LastNamestring Referrer’s Last name.

Authentication Type

Name Value Description
None“None”No third party verification
BankId“BankId”Verification pass via BankId
Tupas“Tupas”Verification pass via Tupas

Form Payments

Name Type Description
SelectedPaymentGetPaymentPaymentMethodInformation about selected Payment method

Payment Method

Name Type Description
TypePaymentMethodTypeType of Payment method
RecurringPaymentCheckBoxStateTypeState of recurring payment check-box
RecurringPaymentTokenstringGenerated recurring payment token

Enumeration States

Each individual Purchase changes its state during a Check-Out session. The following diagram shows valid transitions between the states:

The enumeration describes the state of a single Purchase. Please refer to the diagram in Purchase States chapter to see possible transitions between states.

There are different checkout flow for B2B and B2C purchase mode.

B2C Step Types

NameValueDescription
Initialized0The session has been initialized by a back-end call made by the merchant but the form have not been rendered yet.
EmailZipEntry1The customer is filling-in either the email or ZIP.
SsnEntry2The customer has entered both email and ZIP but it turned out that we also need to know the SSN.
PhoneNumberEntry3Phone number is the 4th thing to ask for (after email, ZIP and SSN) unless it is a known customer.
PhoneNumberEntryForKnownCustomer14Customer was loaded in past steps but without phone. So in this step, we should get only phone value
PersonalInfo4Step for fill in customer info
WaitingForSwish5Waiting for response from Swish application
RedirectedToDirectPaymentBank6The customer has been redirected to a Finnish bank for a direct payment
RedirectedToNets7The customer has been redirected to a card payment provider.
WaitingForBankId8Waiting for response from BankId application
RedirectedToTupas9The customer has been redirected to a Signicat
Completed10The CheckOut has been successfully completed
TimedOut11The sessopn timed
HandledByMerchant12The customer has started external payment method
AwaitingCreditApproval13Waiting for Credit approval from merchant

B2B

NameValueDescription
Initialized0The session has been initialized by a back-end call made by the merchant but the form have not been rendered yet.
EnterCompanyInfo1The customer is company information (email, zip, company SSN, customer SSN).
CompanyAddressInfo3Step for fill in customer info
WaitingForSwish12Waiting for response from Swish application
RedirectedToDirectPaymentBank10The customer has been redirected to a Finnish bank for a direct payment
RedirectedToNets11The customer has been redirected to a card payment provider.
WaitingForBankId8Waiting for response from BankId application
RedirectedToTupas5The customer has been redirected to a Signicat
Completed9The CheckOut has been successfully completed
TimedOut14The sessopn timed