Basic Checkout Request

info

The Hosted Checkout Flow is a simple and secure way to accept payments online. It allows you to redirect your customers to a secure payment page hosted by Straumur. This way, you don't have to worry about handling sensitive payment information on your website.

After the flow, you can find the basic request example below. This example includes all of the required fields for a basic checkout request.

Hosted Checkout Flow

Here is a simple flow chart to help you understand the Hosted Checkout Flow:

1. The merchant (you) initiates a request to create a session.
2. The Hosted Checkout API returns a URL to redirect the user to the hosted checkout page.
3. The user completes the payment on the hosted checkout page.
4. The user is redirected back to the merchant's website.
5. The merchant receives a notification (see Webhooks) about the payment status.
   1. Many payment operations are available after the initial request and they depend on whether the payment is an Authorization or if it has been captured and has become a Transaction. See Payment Lifecycle to learn more about this.
   2. Authorizations will be visible immediately in the Merchant Portal under the "Authorizations" tab.
   3. Transactions will be visible the day after in the Merchant Portal under the "Transactions" tab.

Test URL

Your initial request will be made to the following URL:

https://checkout-api.staging.straumur.is/api/v1/hostedcheckout

This call will create the session and return the URL (see field url from Response) to redirect the user to the hosted checkout page.

Request Example

{
  "amount": "48900",
  "currency": "ISK",
  "returnUrl": "https://your-ecommerce-website.com/straumur_redirect",
  "reference": "9990QQAZ1221",
  "terminalIdentifier": "1adfe4a1"
}

info

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
returnUrl	String	Required	The URL to return to when a redirect payment is completed. Must begin with http:// or https://.	https://your-ecommerce-website.com/straumur_redirect	-	8000
reference	String	Required	The reference to uniquely identify a payment.	9990QQAZ1221	-	-
terminalIdentifier	String	Required	The terminal identifier to uniquely identify the terminal. You can find your Terminal Identifier in the Merchant Portal. Open Section "Terminals" > Select Terminal to open Details panel > Copy Terminal Identifier	1adfe4a1	12	12

Response

{
  "url": "https://hosted-checkout.staging.straumur.is/checkout/d3759bb3655f0f2e4875429e",
  "checkoutReference": "faf984ad76db7b2dea3f7bab",
  "responseDateTime": "2024-09-04T09:50:14.343503Z",
  "responseIdentifier": "7be7111c-2e8e-4cd4-a5ba-f15bdfd177c1"
}

info

After a Checkout Request has been made it is possible to check the status of the payment process by sending a Checkout Status Request.

Response Fields

This table outlines the response fields with their corresponding types, descriptions, examples, and any length constraints.

Field	Type	Description	Example
url	String	The URL to redirect the user to the hosted checkout page.	https://hosted-checkout.staging.straumur.is/checkout/d3759bb3655f0f2e4875429e
checkoutReference	String	The reference to uniquely identify the hosted checkout session.	faf984ad76db7b2dea3f7bab
responseDateTime	String	The date and time when the response was generated.	2024-09-04T09:50:14.343503Z
responseIdentifier	String	The unique identifier for the response.	7be7111c-2e8e-4cd4-a5ba-f15bdfd177c1

Error Response

Our error responses are standardised. Please see Errors.

You can also find a detailed overview of our HTTP Status Codes.