Checkout¶
The checkout API allows you to send a purchase order so that the client can be authenticated and approved.
Idempotency Keys¶
A central concept of the Kronor API is the concept of “Idempotency Keys”.
These are unique strings that are provided by API clients to ensure that operations are processed exactly once. Idempotency Keys are required in almost all operations that mutate any data.
Operations of the same kind sharing the same idempotency key will:
Be processed exactly once
Have the same response, regardless of how many times they are sent
Result in an error if different data is provided for an already processed key
Create a new Order¶
A checkout signifies the intention of a user to pay with our payment options.
Our checkout process is designed to accommodate two common use cases: The merchant server driving the whole process and the rest being done directly in the browser with some interaction with the customer.
Typically, the part that is done by the merchant from the server is sending the contents of the cart, including the description and amounts for each purchased item. The part that is done in the browser by the customer is waiting for the status of the request, performing strong customer authentication and informing the merchant server of the final result of the operation.
You can initiate a new checkout with our API using the newPurchaseOrder mutation. The result of this operation is
a waitToken which is a new API authentication token, safe to use from the browser and scoped to work
exclusively on this new purchase order.
Note
Feel free to explore the “Docs” tab in the editor above to discover all the fields that can be passed as input to this mutation.
Click on mutation_root and navigate to newPurchaseCapture, or just use the search bar and look it up.
Also try using <ctrl> + <space> in both the query and the variables editor above. You will get autocompletion and documentation of all properties.
The returned id field will be equal to the idempotencyKey field you provided, although
we reserve the right to change this in the future.
You need to use the returned token as exposed in the waitToken field in the Authorization
HTTP header to query for the status of the newly created purchase order.
Polling the Order Status¶
Once you have the waitToken from the previous step, you can use it safely from the browser or the backend server
to query the status of the purchase order. You need to use this token as described in the Authentication section.
To query for the checkout status you need to use the purchaseOrders GraphQL node and query its status and
resultingPurchaseId fields.
The status field is an array containing all the statuses the order currently is in. Whenever a purchase order enters
the WAITING_FOR_CAPTURE state, the checkout is considered complete.
The resultingPurchaseId will be a non-null number containing the purchase identifier once the checkout is complete.
You will likely want to save this identifier and associate it with the order number in your own system for future reference.
Hint
Try replacing the token in the “Request Headers” tab in the above editor with
the resulting waitToken of the previous example.
You may poll the status using this query by periodically sending the request or you can also use
a GraphQL subscription over a WebSocket to get real-time changes.
Authenticating with BankID¶
As part of the risk assessment we do for all customers, it may be necessary to perform a strong customer authentication process. In Sweden we use BankID.
Whenever the status fields for the purchaseOrders node contains the SCA_REQUIRED status,
the merchant is required to redirect to our strong customer authentication page in order to complete the
checkout process.
The URL the merchant needs to redirect the cusomter to is:
https://sca.staging.kronor.io/?token=[wait_token]
In the staging environment, the URL is:
{SCA_STAGING_URL}/?token=[wait_token]
Replace the [waitToken] part with the waitToken value returned by the newPurchaseOrder call.
This page will prompt the user to authorize the purchase with BankID and redirect back to the checkout page
as configured for the merchant.
The following query parameters will be added to the redirect URL after succesful authentication:
Query parameter |
Description |
|---|---|
status |
WAITING_FOR_CAPTURE |
reference |
merchant reference |
purchaseId |
ID of the created purchase |
In case authentication fails:
Query parameter |
Description |
|---|---|
status |
REJECTED |
reference |
merchant reference |
You can override the merchant redirect URL by specifying it in the optional success_url parameter.
If the provided URL has any query parameters these will be merged with the parameters listed above.
Get the Purchase Id¶
Using the purchaseOrders GraphQL node, query for the resultingPurchaseId. This field will be the
order number in our system once the checkout process is completed.
{
"data": {
"purchaseOrders": [
{
"status": [
{"status": "WAITING_FOR_CAPTURE"}
],
"resultingPurchaseId": 1
}
]
}
}
There is an alternative way of querying for the purchase id which requires using the merchantReference field
provided when creating the purchase order
The purchases field will remain an empty list until the checkout process is completed successfully.
Cancel the Checkout Process¶
The checkout process can be canceled before it is completed by using the returned id field from
the newPurchaseOrder result. In order to cancel the checkout, you need to use purchaseOrderCancel
The result field will be true if the checkout could be canceled correctly.