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}Response Data Type Description
| Name | Data Type | Description |
|---|---|---|
| PurchaseId | string | The ID that the partner uses to identify the purchase. |
| State | GpsStateType | General state of purchase. |
| ExtraIdentifiers | GetPaymentExtraIdentifiers | Partner’s identifiers |
| TotalPrice | decimal | The total price that the customer has to pay. |
| CreatedUtc | DateTime | UTC time of purchase creations |
| ExpiredUtc | DateTime | UTC time of purchase expiration |
| CheckoutSite | GetPaymentCheckoutSite | Checkout site information |
| Mode | PurchaseMode | Selected purchase mode (B2B/B2C) |
| B2C | GetPaymentB2CState | |
| B2B | GetPaymentB2BState | |
| CardPaymentState | CardState | Information about card payment |
| PaymentMethods | GetPaymentFormPayments | Information about Payment methods |
| AuthenticationType | AuthenticationType | Type of third party authentication |
| CustomerBalance | decimal | CustomerBalance |
Enumeration States
There are different checkout flows for B2B and B2C purchase mode. Current step is described in detail by enumerations: B2BStepType and B2CStepType.
This document describes the mapping of property State type: (GpsStateType) based on detailed B2BStepType and B2CStepType flow steps. The B2BStepType and B2CStepType represent steps that could be extended anytime, while the GpsStateType gives a more specific state depending on the flow used by the customer, such as the payment method.
GpsStateType remains stable and will not be extended.
State Mapping
| GpsStateType | Description | B2CStepType | B2BStepType |
|---|---|---|---|
| PreInitialized | The purchase ID was granted but has not yet been initialized, waiting for the first step. | B2CStepType.PreInitialized | B2BStepType.PreInitialized |
| Initialized | The purchase has been initialized, but no further steps have occurred. | B2CStepType.Initialized | B2BStepType.Initialized |
| InProcess | The purchase is active, and the customer is entering information. | B2CStepType.EmailZipEntry, B2CStepType.SsnEntry, B2CStepType.PhoneNumberEntry, B2CStepType.PersonalInfo, B2CStepType.AmountSelection | B2BStepType.EnterCompanyInfo, B2BStepType.CompanyAddressInfo, B2BStepType.CompanyAddressInfoWithoutSsn |
| WaitingForExternalService | Waiting for an external payment service or third-party action (e.g., BankID). | B2CStepType.WaitingForExternalPaymentService, B2CStepType.WaitingForSwish, B2CStepType.WaitingForTrustly, B2CStepType.WaitingForBankId | B2BStepType.WaitingForBankId, B2BStepType.WaitingForSwish, B2BStepType.WaitingForExternalPaymentService |
| Redirected | The customer has been redirected to an external payment gateway or service. | B2CStepType.RedirectedToDirectPaymentBank, B2CStepType.RedirectedToNets, B2CStepType.RedirectedToTrustly, B2CStepType.RedirectedToVipps, B2CStepType.RedirectedToCheckoutComStep, B2CStepType.RedirectedToNetsEident | B2BStepType.RedirectedToTupas, B2BStepType.RedirectedToDirectPaymentBank, B2BStepType.RedirectedToNets,B2BStepType.RedirectedToNetsEident, B2BStepType.RedirectedToVipps, B2BStepType.RedirectedToCheckoutComStep |
| Completed | The process was successfully completed. | B2CStepType.Completed | B2BStepType.Completed |
| TimedOut | The process timed out due to inactivity. | B2CStepType.TimedOut | B2BStepType.TimedOut |
| HandledByMerchant | The process has been handed over to the merchant for further handling outside the standard flow. | B2CStepType.HandledByMerchant | B2BStepType.HandledByMerchant |
| AwaitingCreditApproval | Waiting for credit approval or payment authorization. | B2CStepType.AwaitingCreditApproval | B2BStepType.AwaitingCreditApproval |
| CreditNotApproved | Credit approval was not granted. | B2CStepType.CreditNotApproved | B2BStepType.CreditNotApproved |
| Canceled | The process was canceled by the partner or the system. | B2CStepType.Canceled | B2BStepType.Canceled |
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 the Purchase States chapter to see possible transitions between states.
B2C Step Types
| Name | Value | Description |
|---|---|---|
| PreInitialized | 26 | The session has been registered, and a Purchase ID has been reserved. The customer must load the checkout within 24 hours. |
| Initialized | 0 | The session has been initialized by a back-end call made by the merchant but the form have not been rendered yet. |
| EmailZipEntry | 1 | The customer is filling-in either the email or ZIP. |
| SsnEntry | 2 | The customer has entered both email and ZIP but it turned out that we also need to know the SSN. |
| PhoneNumberEntry | 3 | Phone number is the 4th thing to ask for (after email, ZIP and SSN) unless it is a known customer. |
| PhoneNumberEntryForKnownCustomer | 14 | Customer was loaded in past steps but without phone. So in this step, we should get only phone value |
| PersonalInfoWithoutSsn | 15 | Step for flow without social security number |
| PersonalInfo | 4 | Step for fill in customer info |
| WaitingForSwish | 5 | Waiting for response from Swish application |
| RedirectedToDirectPaymentBank | 6 | The customer has been redirected to a Finnish bank for a direct payment |
| RedirectedToNets | 7 | The customer has been redirected to a card payment provider. |
| WaitingForBankId | 8 | Waiting for response from BankId application |
| RedirectedToTupas | 9 | The customer has been redirected to a Signicat |
| Completed | 10 | The CheckOut has been successfully completed |
| TimedOut | 11 | The session is timed out |
| HandledByMerchant | 12 | The customer has initiated an external payment method |
| AwaitingCreditApproval | 13 | Waiting for Credit approval from merchant |
| RedirectedToNetsEident | 17 | The customer has been redirected to a Nets E-ident provider |
| Canceled | 16 | The purchase is cancelled |
| RedirectedToVipps | 21 | The customer has been redirected to Vipps |
| CreditNotApproved | 22 | High loan order was not approved |
| RedirectedToCheckoutComStep | 23 | The customer has been redirected to a card provider |
| WaitingForOtp | 25 | Waiting for e-mail or phone verification of customer |
B2B Step Types
| Name | Value | Description |
|---|---|---|
| PreInitialized | 21 | The session has been registered, and a Purchase ID has been reserved. The customer must load the checkout within 24 hours. |
| Initialized | 0 | The session has been initialized by a back-end call made by the merchant but the form have not been rendered yet. |
| EnterCompanyInfo | 1 | The customer is company information (email, zip, company SSN, customer SSN) step. |
| CompanyAddressInfo | 3 | Step for fill in customer info |
| WaitingForSwish | 12 | Waiting for response from Swish application |
| RedirectedToDirectPaymentBank | 10 | The customer has been redirected to a Finnish bank for a direct payment |
| RedirectedToNets | 11 | The customer has been redirected to a card payment provider. |
| WaitingForBankId | 8 | Waiting for response from BankId application |
| RedirectedToTupas | 5 | The customer has been redirected to a Signicat |
| Completed | 9 | The CheckOut has been successfully completed |
| HandledByMerchant | 13 | The customer has initiated an external payment method |
| TimedOut | 14 | The session is timed out |
| Canceled | 15 | The purchase is cancelled |
| RedirectedToNetsEident | 16 | The customer has been redirected to a Nets E-ident provider |
| RedirectedToVipps | 18 | The customer has been redirected to Vipps |
| RedirectedToCheckoutComStep | 19 | The customer has been redirected to a card provider |