Basic Session Request
POST /embeddedcheckout/session
The Embedded Checkout Flow is a simple and secure way to accept payments directly on your website.
It allows you to integrate Straumur's web component, which securely handles all sensitive payment information.
This way, you can offer a seamless payment experience without needing to manage PCI compliance yourself.
After the flow, you can find the basic request example below.
This example includes all of the required fields for a basic checkout request.
Flow
Test URL
Your initial request will be made to the following URL:
POST https://checkout-api.staging.straumur.is/api/v1/embeddedcheckout/session
This call will create the session and return the checkout reference and session id that you will pass to your frontend component.
On live, use the same path on https://greidslugatt.straumur.is. Headers, request and response are identical. See Live environment.
Request Example
{
"amount": 48900,
"currency": "ISK",
"origin": "https://www.your-ecommerce-website.com",
"reference": "9990QQAZ1221",
"terminalIdentifier": "1adfe4a1b2c3",
"threeDsReturnUrl": "https://your-ecommerce-website.com/straumur_redirect"
}
Amount in request should be specified in minor units.
For more information on minor units, please see Currencies and Minor Units.
Request Required Fields
This table outlines the request required fields with their corresponding types, descriptions, examples, and any length constraints.
| Field | Type | Required | Description | Example | Min Length | Max Length |
|---|---|---|---|---|---|---|
| amount | Integer | Required | The amount to be charged in minor units. Must end in 00 for ISK. | 48900 | - | - |
| currency | String | Required | The three-character ISO currency code. | ISK | 3 | 3 |
| origin | String | Required | Location where the payment originates from. This must be in line with the channel provided. | https://www.your-ecommerce-website.com | - | - |
| reference | String | Required | The reference to uniquely identify a payment. | 9990QQAZ1221 | - | 200 |
| terminalIdentifier | String | Required | The terminal identifier that uniquely identifies the terminal used for this request. See Terminal Identifier for how to find it in the Merchant Portal and what to do if it's missing. | 1adfe4a1b2c3 | 12 | 12 |
| threeDsReturnUrl | String | Required | Location where the shopper should be redirected back to if 3DS occurs as a redirect. This must be in line with the channel provided. | https://www.your-ecommerce-website.com/straumur_additional_details | - | - |
Response
{
"checkoutReference": "12f76ahtugvewe1cewijsfrsygazatjki6a5z7lskcfoxb3g5h",
"responseDateTime": "2024-09-04T10:35:18.343503Z",
"responseIdentifier": "e4ce3367-4d2b-4398-ad4e-06bcee650104",
"sessionId": "ftsdre3h...e5h5as2q4",
}
Response Fields
This table outlines the response fields with their corresponding types, descriptions, examples, and any length constraints.
| Field | Type | Description | Example |
|---|---|---|---|
| checkoutReference | String | The reference to uniquely identify the hosted checkout session. | faf984ad76db792v76ahtugvewe1cewijsfrsygaz |
| responseDateTime | String | The date and time when the response was generated. | 2025-01-04T09:50:14.343503Z |
| responseIdentifier | String | The unique identifier for the response. | 7be7111c-2e8e-4cd4-a5ba-f15bdfd177c1 |
| sessionId | String | The unique identifier of the created session. You can use this value to query session status. | e5h5as2q4ftsdre3h... |
Error Response
Our error responses are standardised. Please see Errors, including troubleshooting for Origin, Return URL, and Terminal Identifier errors.
You can also find a detailed overview of our HTTP Status Codes.