Create Order

An order is always created against the terminal$id obtained after terminal registration. This includes line items with their respective prices and serves as the initial step for initiating a payment, forming the basis of the payment flow. Each payment attempt must be linked to an order using its orderId, which is essential for efficient transaction processing.

Prerequisites

API Credentials

API-KEY, API-SECRET, and MERCHANT-ID required for API access

Terminal ID

terminal$id of the registered terminal obtained via Register Terminal API

Create an Order

Make POST Request

Make a POST request to the Create New Order API with the essential details:

terminal$id: ID of the registered terminal for creating the order
type: Specify the order type as "purchase"
orderLines: List the products in the order, including product ID, product name, and quantity

Receive Order ID

The request will return an Order ID, a unique identifier for the created order. This Order ID is required for:

Initiating payment
Checking order status
Processing returns and refunds

Initiate Payment

You can initiate a payment using any supported/active method, and once successful, the status will be updated to PAYMENT_COMPLETED.

Example Request

$ curl -X POST \
>   -d '{
>     "terminal$id": "a1b2c3d4e5f6g7h8i9",
>     "type": "purchase",
>     "referenceId": "POS-RECEIPT-001",
>     "orderLines": [
>       {
>         "id": "ITEM-001",
>         "name": "Product Name",
>         "quantity": 2,
>         "amount": {
>           "regular": 15000,
>           "total": 30000,
>           "currency": "578",
>           "tax": [
>             {
>               "amount": 6000,
>               "percentage": 25,
>               "type": "vat"
>             }
>           ]
>         }
>       }
>     ],
>     "totalOrderAmount": {
>       "regular": 30000,
>       "total": 30000,
>       "currency": "578",
>       "tax": [
>         {
>           "amount": 6000,
>           "percentage": 25,
>           "type": "vat"
>         }
>       ]
>     }
>   }' \
>   -H 'Content-Type: application/json' \
>   -H 'API-KEY: your-api-key' \
>   -H 'API-SECRET: your-api-secret' \
>   -H 'MERCHANT-ID: your-merchant-id' \
>   'https://api.sagapay.no/orders'

Example Response

1 {
2   "status": "SUCCESS",
3   "data": {
4     "orderId": "834bf5f923fa88090b",
5     "orderStatus": "PENDING",
6     "createdAt": "2026-01-24T10:30:00.000Z"
7   },
8   "message": "Order created successfully"
9 }

Order Parameters Reference

Terminal & Order Identification

Parameter	Type	Required	Description
`terminal$id`	string	Required	Unique identifier of the terminal used for processing payments
`type`	string	Required	Order type: `"purchase"` for buying goods/services, `"return"` for returning previously purchased products
`date`	string	Optional	Date of the order created
`referenceId`	string	Required	External identification for reference of the created order
`purchaseOrderId`	string	Conditional	Mandatory for return orders - links to original purchase

Company Purchase Details

Parameter	Type	Required	Description
`companyPurchase`	boolean	Optional	Set to `true` when purchases are made on behalf of an organization
`company`	object	Optional	Company information for the order
`company.id`	string	Required	ID of the company purchased for
`company.vatId`	string	Optional	VAT ID of the company
`company.poDetails`	string	Required	Additional purchase order details

Customer Information

Parameter	Type	Required	Description
`customer`	object	Optional	All relevant customer details
`customer.person`	object	Optional	Personal details of the customer
`customer.person.id`	string	Required	Customer’s ID
`customer.person.name.firstName`	string	Optional	First name
`customer.person.name.middleName`	string	Optional	Middle name
`customer.person.name.lastName`	string	Optional	Last name
`customer.person.email`	string	Optional	Customer’s email
`customer.person.phoneNumber.code`	number	Required	International dialing code
`customer.person.phoneNumber.number`	string	Required	Phone number (5-15 digits)
`customer.person.birthDate`	string	Optional	Date of birth (YYYY-MM-DD)
`customer.person.nationalId`	string	Optional	Government-issued unique identifier
`customer.person.nationalIdType`	string	Optional	Type of national ID
`customer.person.countryResidence`	string	Optional	Country of residence (ISO 2-letter code)

Billing Details

Parameter	Type	Required	Description
`customer.billing`	object	Optional	Customer’s billing address
`customer.billing.careOf`	string	Optional	C/O name for correspondence
`customer.billing.address1`	string	Required	Address line 1
`customer.billing.address2`	string	Optional	Address line 2
`customer.billing.address3`	string	Optional	Address line 3
`customer.billing.city`	string	Required	City
`customer.billing.postalCode`	string	Required	Postal code
`customer.billing.country`	string	Required	Country (ISO 2-letter code)

Shipping Details

Parameter	Type	Required	Description
`shipping`	object	Optional	Shipping address details
`shipping.name.firstName`	string	Required	Recipient’s first name
`shipping.name.middleName`	string	Optional	Recipient’s middle name
`shipping.name.lastName`	string	Required	Recipient’s last name
`shipping.email`	string	Required	Recipient’s email
`shipping.phoneNumber.code`	number	Required	International dialing code
`shipping.phoneNumber.number`	string	Required	Phone number (5-15 digits)
`shipping.careOf`	string	Optional	C/O name
`shipping.address1`	string	Required	Shipping address line 1
`shipping.address2`	string	Optional	Shipping address line 2
`shipping.address3`	string	Optional	Shipping address line 3
`shipping.city`	string	Required	Delivery city
`shipping.postalCode`	string	Required	Postal code
`shipping.country`	string	Required	Country (ISO 2-letter code)

Order Line Items

Parameter	Type	Required	Description
`orderLines`	array	Required	Collection of items in the order
`orderLines[].id`	string	Required	Item ID
`orderLines[].categoryId`	string	Optional	Category ID for item organization
`orderLines[].name`	string	Required	Name of the item
`orderLines[].description`	string	Optional	Description of the item
`orderLines[].quantity`	number	Required	Quantity of the item
`orderLines[].gtin`	string	Optional	Global Trade Item Number (14 digits)
`orderLines[].imageUrl`	string	Optional	Image URL of the item
`orderLines[].brand`	string	Optional	Brand of the item
`orderLines[].unit`	string	Optional	Metric unit (see supported units below)

Supported Units: m, mm, cm, km, in, ft, mi, kg, g, mg, lb, oz, l, ml, cu. m, gal, pt, fl oz, W, kW, kWh, sq m, sq km, sq ft, h, min, s, days, wk, mn, yr, nos

Item Amount

Parameter	Type	Required	Description
`orderLines[].amount`	object	Required	Price details of the item
`orderLines[].amount.regular`	number	Required	Regular price (minor units)
`orderLines[].amount.campaign`	number	Optional	Campaign/discount price
`orderLines[].amount.shipping`	number	Optional	Shipping price
`orderLines[].amount.total`	number	Required	Total payable amount
`orderLines[].amount.currency`	string	Required	Currency (ISO 4217 numeric code, e.g., `"578"` for NOK)
`orderLines[].amount.tax`	array	Required	Tax details array
`orderLines[].amount.tax[].amount`	number	Required	Tax amount
`orderLines[].amount.tax[].percentage`	number	Required	Tax percentage
`orderLines[].amount.tax[].type`	string	Required	Tax type (currently `"vat"`)

Amount Calculation

If orderLineLevelCalculation is TRUE: total = (regular × quantity) - campaign + shipping
If orderLineLevelCalculation is FALSE: total = regular - campaign + shipping

Campaign Details

Parameter	Type	Required	Description
`orderLines[].campaign`	object	Optional	Campaign details
`orderLines[].campaign.externalCampaign`	boolean	Required	Whether it’s an external campaign
`orderLines[].campaign.id`	string	Optional	Campaign ID
`orderLines[].campaign.name`	string	Required	Campaign name

Total Order Amount

Parameter	Type	Required	Description
`totalOrderAmount`	object	Optional	Total breakdown of the order
`totalOrderAmount.regular`	number	Required	Sum of all item regular prices
`totalOrderAmount.campaign`	number	Optional	Total campaign discount
`totalOrderAmount.shipping`	number	Optional	Total shipping cost
`totalOrderAmount.total`	number	Required	Total payable for the order
`totalOrderAmount.currency`	string	Required	Currency (ISO 4217 numeric code)
`totalOrderAmount.tax`	array	Required	Order-level tax details

Adjustments & Metadata

Parameter	Type	Required	Description
`adjustments`	array	Optional	Add or deduct from total (e.g., Tips, Charity, Gift cards)
`adjustments[].type`	string	Required	Adjustment type
`adjustments[].value`	string	Required	Adjustment value
`metaData`	object	Optional	Additional data in key-value pairs

Total order amount = regular + shipping - campaign + adjustments

Control Functions

Control functions allow you to customize the order processing behavior.

Order Management Controls

Parameter	Type	Required	Description
`controlFunctions.cancelPreviousPendingOrder`	boolean	Optional	Set `true` to cancel all previous pending orders
`controlFunctions.orderLineLevelCalculation`	boolean	Optional	Set `true` to apply campaign/shipping at row level
`controlFunctions.includeAdjustments`	boolean	Optional	For returns: include adjustments in refund (default: `true`)

Payment Processing Options

Parameter	Type	Required	Description
`controlFunctions.payButtonType`	string	Optional	Customize payment button text. Values: `ADD_MONEY`, `BOOK`, `BUY`, `CHECKOUT`, `CONTINUE`, `DONATE`, `ORDER`, `PAY`, `RENT`, `SUBSCRIBE`, `SUPPORT`, `TIP`, `TOP_UP`
`controlFunctions.lockToPaymentMethods`	array	Optional	Lock to specific methods: `CARD`, `SSWISH`
`controlFunctions.delayCapture`	boolean	Optional	Allows capture at a later date
`controlFunctions.delayPayout`	string	Optional	Delay payout (format: `"7m"` for 7 minutes)
`controlFunctions.authMode`	string	Optional	`PRE-AUTH` or `AUTH` (default). PRE-AUTH sets delayCapture to true

Notification and Error Handling

Parameter	Type	Required	Description
`controlFunctions.callBackUrl`	string	Optional	Dynamic webhook URL for order-related callbacks
`controlFunctions.throwErrorIfTerminalInactiveFor`	number	Optional	Error if terminal inactive for X seconds

Terminal Interaction (NFC)

Parameter	Type	Required	Description
`readTags`	string	Optional	NFC reading mode: `NONE`, `SINGLE`, `MULTIPLE_EDITABLE`, `MULTIPLE_NONEDITABLE`

Online Payment Settings

Parameter	Type	Required	Description
`online.enforceTokenization`	boolean	Optional	Tokenize card for future transactions
`online.paymentPageValidFor`	string	Optional	Payment page validity (format: `"30m"`)
`online.redirectUrl`	string	Optional	Redirect URL after transaction (orderId added as query param)
`online.failureRedirectUrl`	string	Optional	Redirect URL for failed transactions
`online.generateShortLink`	boolean	Optional	Generate short URL for payment page

Recurring Payments

Parameter	Type	Required	Description
`recurring.subscriptionAmountType`	string	Required	`"fixed"` or `"variable"`
`recurring.maxAmount`	number	Optional	Max amount for variable subscriptions (minor units)
`recurring.frequency`	string	Conditional	Required for subscriptions: `daily`, `twiceWeekly`, `weekly`, `tenDays`, `fortNightly`, `monthly`, `everyTwoMonths`, `trimester`, `quarterly`, `twiceYearly`, `annually`, `unscheduled`
`recurring.numberOfPayments`	number	Optional	Expected total payment count
`recurring.uniqueReference`	string	Optional	Unique reference for recurring order

If merchants need to make changes to an existing order before initiating payments, they can update the order using the Update Order API. However, merchants cannot update the order after initiating a payment.

Initiate a Payment

Once you create an order, you can initiate payments through a checkout system or registered payment terminal. Each payment attempt is linked to the created order using the orderId.

Prerequisites

API Credentials

API-KEY, API-SECRET, and MERCHANT-ID

Order ID

orderId received from the Create Order response

Initiate Payment

Make Payment Request

Make a request with the orderId to the Initiate Payment API endpoint. Specify the paymentMethod:

Payment Method	Description
`CARD`	Card present payment (default)
`CARD_NP`	Card not present (for refunds)
`KLARNA`	Klarna payment
`SWISH`	Swish payment

Receive Payment ID

After successful initiation, a unique paymentId will be generated. Store this securely for:

Tracking payment status
Processing refunds
Other payment-related actions

Example Request

$ curl -X POST \
>   -d '{
>     "orderId": "834bf5f923fa88090b",
>     "paymentMethod": "CARD"
>   }' \
>   -H 'Content-Type: application/json' \
>   -H 'API-KEY: your-api-key' \
>   -H 'API-SECRET: your-api-secret' \
>   -H 'MERCHANT-ID: your-merchant-id' \
>   'https://api.sagapay.no/payments'

Example Response

1 {
2   "status": "SUCCESS",
3   "data": {
4     "paymentId": "pay_x1y2z3a4b5c6",
5     "orderId": "834bf5f923fa88090b",
6     "paymentStatus": "INITIATED",
7     "paymentMethod": "CARD"
8   },
9   "message": "Payment initiated successfully"
10 }

To enable partial payments, specify the desired payment amount in the smallest currency unit within the amount parameter.

Fetch Order Status

Tracking the order status is crucial for ensuring smooth payment processing and addressing any errors or issues that could impact the payment completion.

Prerequisites

API Credentials

API-KEY, API-SECRET, and MERCHANT-ID

Order ID

orderId received from the Create Order response

Fetch Status

Make Status Request

Include the orderId in the Fetch Order Status API request.

Check Order Status

The response will include one of the following statuses:

Status	Description
`PENDING`	Order created, awaiting payment processing
`PAYMENT_COMPLETED`	Payments fully completed
`PAYMENT_CANCELLED`	Payment attempt cancelled
`PARTIAL_PAYMENT_COMPLETED`	Payment partially completed

Get Payment IDs

If status is PAYMENT_COMPLETED, the response includes an array of payment IDs.

Example Request

$ curl -X GET \
>   -H 'Content-Type: application/json' \
>   -H 'API-KEY: your-api-key' \
>   -H 'API-SECRET: your-api-secret' \
>   -H 'MERCHANT-ID: your-merchant-id' \
>   'https://api.sagapay.no/orders/834bf5f923fa88090b/status'

Example Response

1 {
2   "status": "SUCCESS",
3   "data": {
4     "orderId": "834bf5f923fa88090b",
5     "orderStatus": "PAYMENT_COMPLETED",
6     "payments": [
7       {
8         "paymentId": "pay_x1y2z3a4b5c6",
9         "paymentStatus": "SUCCESS",
10         "paymentMethod": "CARD",
11         "amount": 30000
12       }
13     ],
14     "completedAt": "2026-01-24T10:35:00.000Z"
15   },
16   "message": "Order status retrieved successfully"
17 }

You can also get order status updates by integrating webhooks, which provide real-time updates on payment events directly, eliminating the need for frequent polling.

Next Steps

After the order is completed, merchants can:

Process Returns

Create return orders for refunds

View Transactions

Check transaction history