Checkout 3.0
Finalize Purchase

On this page, you will find information about how to Process the result and the different Purchase states throughout 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 the payment status API function

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}
{
  "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
}

Response Data Type Description

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
ExpiredUtcDateTimeUTC time of purchase expiration
CheckoutSiteGetPaymentCheckoutSiteCheckout site information
ModePurchaseModeSelected purchase mode (B2B/B2C)
B2CGetPaymentB2CState
B2BGetPaymentB2BState
CardPaymentStateCardStateInformation about card payment
PaymentMethodsGetPaymentFormPaymentsInformation about Payment methods
AuthenticationTypeAuthenticationTypeType of third party autherntication
CustomerBalancedecimalCustomerBalance

Enumeration States

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

Checkout3 purchase states diagram

The enumeration describes the state of a single Purchase. Please refer to the diagram in the 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
PersonalInfoWithoutSsn15Step for flow without social security number
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 session is timed out
HandledByMerchant12The customer has initiated an external payment method
AwaitingCreditApproval13Waiting for Credit approval from merchant
RedirectedToNetsEident17The customer has been redirected to a Nets E-ident provider
Canceled16The purchase is cancelled
RedirectedToVipps21The customer has been redirected to Vipps

B2B 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.
EnterCompanyInfo1The customer is company information (email, zip, company SSN, customer SSN) step.
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
HandledByMerchant13The customer has initiated an external payment method
TimedOut14The session is timed out
Canceled15The purchase is cancelled
RedirectedToNetsEident16The customer has been redirected to a Nets E-ident provider
RedirectedToVipps18The customer has been redirected to Vipps
Custom StylesOrder Management