Carts | Checkout

Add payments to existing cart

Register payment transaction(s) from your payment provider on the cart.

The transactionId is typically provided by the payment provider and is often a GUID. This ID ties together related transactions - the same transactionId is for instance used for authorization, capture, and credit operations on the same payment.

For e-commerce orders: Use transactionType "Authorization" - Omnium workflows handle Capture/Credit/Void automatically.

For POS: Use transactionType "Sale" since payment is captured immediately.

Example - E-commerce payment (Klarna):

PUT /api/carts/{cartId}/AddPayments
[
    {
        "amount": 999.00,
        "paymentMethodName": "Klarna",
        "transactionId": "klarna-order-abc123",
        "transactionType": "Authorization",
        "status": "Processed"
    }
]

Example - POS sale:

PUT /api/carts/{cartId}/AddPayments
[
    {
        "amount": 599.00,
        "paymentMethodName": "Card",
        "transactionId": "terminal-tx-12345",
        "transactionType": "Sale",
        "status": "Processed"
    }
]

Example - Split payment (Gift card + Vipps):

PUT /api/carts/{cartId}/AddPayments
[
    {
        "amount": 200.00,
        "paymentMethodName": "GiftCard",
        "transactionId": "GC-ABC123",
        "transactionType": "Authorization",
        "status": "Processed"
    },
    {
        "amount": 799.00,
        "paymentMethodName": "Vipps",
        "transactionId": "vipps-order-xyz",
        "transactionType": "Authorization",
        "status": "Processed"
    }
]
put/api/Cart/{cartId}/AddPayments

Request

  • Base URL: https://api.omnium.no (the document declares no server; this is the origin it was published from)
  • URL: https://api.omnium.no/api/Cart/{cartId}/AddPayments
  • Auth: API key in header Authorization

Path parameters

cartIdstring nullable required

ID of existing cart. (Required)

Query parameters

overwriteExistingboolean

Indicates whether to overwrite existing payments. Defaults to true. If true, replaces existing payments. If false, appends new payments

Request body

amountnumber

The monetary amount for this payment transaction. For Authorization: The reserved/authorized amount For Capture: The captured amount (can be less than or equal to authorization) For Credit/Refund: The refunded amount

authorizationCodestring nullable

Authorization code returned by the payment provider. Used for reference and reconciliation with the payment provider.

customerNamestring nullable

Name of the customer associated with this payment.

implementationClassstring nullable

Not in use - reserved for internal purposes.

idstring nullable

Unique identifier for this specific payment record in Omnium. Different from TransactionId which is the provider's reference. When updating payments, matching is done on this Id.

paymentIdinteger

Deprecated. Use TransactionId instead.

paymentMethodIdstring uuid

Deprecated. Use PaymentMethodName instead.

paymentMethodNamestring nullable

Identifies the payment provider. Must match a configured provider name in Omnium. Examples: "Klarna", "Vipps", "Stripe", "Adyen", "GiftCard", "Dintero" This determines which integration Omnium uses for capture/refund operations.

paymentTypestring nullable

Sub-type or method within the payment provider. Examples: "Invoice", "Card", "Swish", "DirectDebit" Used to identify the specific payment method when a provider offers multiple options.

statusstring nullable

Current status of this payment transaction. Values:

  • "Processed": Transaction completed successfully
  • "Failed": Transaction failed
  • "Pending": Awaiting processing or confirmation
  • "Paid": Payment has been paid
  • "Approved": Payment has been approved
transactionIdstring nullable

Unique transaction identifier from the payment provider. This is the provider's reference for the transaction and is required for subsequent operations (capture, refund). Example: Klarna order ID, Vipps order ID, Stripe payment intent ID

transactionTypestring nullable

The type of payment transaction.

Common values for API consumers:

  • "Authorization": Payment is reserved but not yet captured. Standard for e-commerce orders
  • "Capture": Payment has been captured/charged from the customer
  • "Sale": Payment is immediately captured (no separate authorization). Use for POS/in-store orders
  • "Credit": Refund/credit back to the customer
  • "Invoiced": Invoice-based payment (e.g., Klarna invoice)
  • "Void": Authorization has been cancelled/voided

Internal/system values (typically set by Omnium, not API consumers):

  • "AwaitingAuthorization": Used internally for paylinks and in-store payments awaiting customer action
  • "ReleaseRemainingAuthorization": Release unused authorization amount after partial capture
  • "Settlement", "SettlementFee", "SettlementRefund": Provider settlement transactions
  • "Bookkeeping", "CreditBookkeeping": Internal accounting transactions
  • "Other": Other transaction types

For POS/in-store sales, use "Sale" since payment is captured immediately at point of sale. For e-commerce orders, use "Authorization" - Omnium workflows handle Capture, Credit, and Void automatically.

validationCodestring nullable

Deprecated. Not in use.

paidDatestring date-time nullable

The original date when the payment was made. May differ from Created if the payment was pre-paid or processed externally before registration.

createdstring date-time nullable

Timestamp when this payment record was created/registered in Omnium.

isManuallyAddedboolean

Indicates if this payment was manually added through the Omnium UI rather than from a payment provider integration. Manual payments are typically used for cash, bank transfer, or other offline payment methods.

isVirtualboolean nullable

Indicates that this entry moves value between orders rather than money that went through a payment provider or a cash register. Set on both sides of a transfer: "Credit" on the order the value left (see Omnium.Public.Payments.Models.OmniumPayment.TransferredToOrderId) and "Sale"/"Authorization"/"Capture" on the order it arrived at (see Omnium.Public.Payments.Models.OmniumPayment.TransferredFromOrderId).

This happens on in-store returns and exchanges: the returned goods pay for the new goods instead of being refunded and re-charged, and Omnium records the return as its own order, so the original payment must appear on both for the totals to add up. A refund the provider really executed is never virtual, even on a return order.

Virtual entries still count towards the order's payment totals, but nothing exists at the provider or terminal — skip them when reconciling against a settlement.

transferredFromOrderIdstring nullable

Order the value came from. Set on the receiving side of a transfer, with Omnium.Public.Payments.Models.OmniumPayment.IsVirtual.

transferredToOrderIdstring nullable

Order the value went to. Set on the originating side of a transfer, with Omnium.Public.Payments.Models.OmniumPayment.IsVirtual.

commentstring nullable

Free-text comment or note about the payment. Useful for manual payments or special circumstances.

internalReferencestring nullable

Internal reference for linking this payment to other business documents. Can be used for RMA numbers, related order numbers, or other cross-references.

reasonstring nullable

Description or reason for the payment, especially useful for refunds/credits. Example: "Return of damaged item", "Partial refund for shipping delay"

authorizationExpiresstring date-time nullable

Expiration date/time for the authorization from the payment provider. After this date, the authorization may no longer be valid for capture. Important for managing capture timing and avoiding authorization expiry.

storeIdstring nullable

The store or warehouse ID associated with this payment. Used for multi-store scenarios where payments need to be attributed to specific locations.

shipmentIdstring nullable

The shipment ID this payment is associated with. Used when payments are split across multiple shipments or for shipment-specific captures.

fiscalSaleIdstring nullable

The POS fiscal sale this payment belongs to: the payment event at the till that paid for a selection of the order's shipments and produced one receipt. Shared by every payment in a split tender.

invoiceIdstring nullable

Reference to an invoice if this payment is linked to an invoice document. Used for invoice-based payment methods or accounting integrations.

reservationIdstring nullable

Reference from some payment providers where transaction id diff from a reservation/auth

Response

Payments are added, and updated cart is returned

idstring nullable

Cart unique ID

expiredDatestring date-time nullable

Expiration date of cart. If passed, the cart should not be visible to customer.

isReadOnlyboolean

Should the cart be read only?

isReadOnlyByCustomerboolean

Should the order/cart be read only for the customer?

ignorePromotionsboolean nullable

Should promotion prices be ignored when product is added to cart?

customerGroupsstring[] nullable

Customer groups (for discount calculation)

orderStatusstring nullable

Should be used when order needs a special status when created from cart

orderNumberstring nullable

In most cases, this property will be identical to the Id property. However, if you have orders from multiple sources (multiple e-commerce sites, pos systems or other sales channels), and the order numbers from the sources could overlap, you could set the Id to a unique value and the order number to the user friendly number.

customerIdstring nullable

The ID of the customer that has placed the order. Typically this is set to the customers phone number or email address, but it could be set to anything. A customer with the matching ID does not have to exist in the system before the order is placed. If there are no overlapping IDs, but you still have multiple sources of IDs, consider using ExternalIds instead.

customerNumberstring nullable

In most cases, the customer number could be set to the same value as the CustomerId. However, in some edge cases the customers could get imported from multiple systems with the same ID range. In that case, you should set the user friendly number to the CustomerNumber and an unique ID for the CustomerId.

customerClubMemberIdstring nullable

If Customer is member of customer club, set Customer ID as member ID.

billingCurrencystring nullable

Currency of the order. e.g. "USD","NOK"

customerNamestring nullable

Full name of customer

customerPhonestring nullable

Customer phone number with prefix. e.g. +4740000000

customerEmailstring nullable

Customer e-mail

customerTypestring nullable

B2B or B2C (Business customer or private customer)

marketIdstring nullable

Market ID e.g. "US", "NOR", "SWE". This must match the value of the market(s) defined in Omnium.

shippingDiscountTotalnumber

(OBSOLETE: Use property on OrderForm instead) Shipping discount amount

shippingSubTotalnumber

Total shipping cost

statusstring nullable

The current order status. This must match a status defined in the order settings in Omnium. Typical values are "New", "InProgress", "Cancelled" or "Completed".

remainingPaymentnumber

CALCULATED: The remaining payment amount if the difference between the authorized amount and total amount

salesPersonIdstring nullable

Id of seller of the order - typically set to the e-mail of the user in Omnium, but could be set to any ID.

salesPersonNamestring nullable

Name of the seller of the order

salesChannelstring nullable

Name of sales channel

completedstring date-time nullable

CALCULATED: Order completed date

modifiedstring date-time

CALCULATED: Order last modified date

modifiedBystring nullable

CALCULATED: Modified by

createdstring date-time

The creation date of the order

receivedstring date-time nullable

The received date of the order

followUpDatestring date-time nullable

Order follow-up date

customerPickupDeadlinestring date-time nullable

CALCULATED: Customer deadline for picking up order

storePickDatestring date-time nullable

CALCULATED: Employee deadline for picking order

requestedDeliveryDatestring date-time nullable

Delivery date requested by customer

updateStatusDatestring date-time nullable

Date when order should be moved to next status. (Updated by UpdateOrderStatusScheduledTask)

readyForPickupstring date-time nullable

Calculated: When the order was set to ready for pickup. The property can be set by workflow step with name: Set ready for pickup date

nextOrderStatusstring nullable

Status order should be moved to. (Updated by UpdateOrderStatusScheduledTask)

paymentTypestring nullable

OBSOLETE: Use orderForm.payments instead.

orderTypestring nullable

Order type e.g. "Online", "Pos". The order type must match a order type defined in the Omnium order settings

requestedAllocationProfileKeystring nullable

The allocation profile Omnium's allocation engine should rank plans under for this order, for example FewestShipments or Closest. Empty means the profile configured for the market.

storeIdstring nullable

The store Id identifies the store that sells the orders. Should match an ID of an existing store. A store would typically be the front end e-commerce solution, a physical store or other sales channels.

orderOriginstring nullable

The origin of the order should identify where the order was created. Typical values are "OMS", "ERP", "WEB" or "POS".

lineItemsCostnumber

Calculated: Total cost of the order. The cost price

netTotalnumber

Calculated: OrderForm total - returnForms total

netTotalExclTaxnumber

Calculated: OrderForm total excl tax - returnForms total excl tax

customerReferencestring nullable

Reference provided by customer.

customerContactstring nullable

Customer contact person

customerRequisitionstring nullable

Customer requisition provided by customer

isNotificationsDisabledboolean

If true, Omnium's notifications will not be triggered for the order

relatedOrdersstring[] nullable

List of related order IDs

sessionstring nullable

Session code used for referencing a web session

secretKeystring nullable

A unique secret key for the order. Can be used for secure order lookups.

replacementOrderIdsstring[] nullable

List of replacement order IDs for this order

subscriptionIdstring nullable

Subscription ID - used if order is part of a subscription. The Id should match an existing subscription in Omnium

projectIdsstring[] nullable

Project IDs - used if order is part of projects

tagsstring[] nullable

Order tags (Used by notification filters, and for grouping / filtering orders)

paymentTermsNetinteger nullable

Net payment terms (in days). Used for invoice due dates.

invoiceCommentstring nullable

Invoice comment

projectIdstring nullable

OBSOLETE: Use ProjectIds instead. Project ID - used if order is part of a project

subTotalnumber

(OBSOLETE: Use property on OrderForm instead) Order total without shipment cost

subTotalExclTaxnumber

(OBSOLETE: Use property on OrderForm instead) Order total without shipment cost and without tax

taxTotalnumber

(OBSOLETE: Use property on OrderForm instead) Total tax amount

totalnumber

(OBSOLETE: Use property on OrderForm instead) Order total, including shipment cost, tax, and discounts

totalExclTaxnumber

(OBSOLETE: Use property on OrderForm instead) Order total, including shipment cost and discounts, but without tax

discountTotalIncVatnumber

(OBSOLETE: Use property on OrderForm instead) Total order discount

isNewCustomerboolean nullable

Indicates whether the customer is new. Set automatically by the workflow if the customer's creation date is in the past, but can also be updated via the API.

versionIdstring nullable

Read only: Current version ID

namestring nullable

Order name

canceledstring date-time nullable

Canceled date

orgNrstring nullable

Organization number

correlationIdstring nullable

Correlation ID for tracing

isAnonymizedboolean

Whether the order has been anonymized

isReservableboolean nullable

Whether the order is reservable

invoiceIdsstring[] nullable

List of invoice IDs associated with this order

documentStatusstring nullable

Shows which documents have been generated for the order

customerOrderNumberstring nullable

Customer's own order number

isReallocatedboolean

Whether the order has been reallocated

Changes

No recorded changes to this operation across all 1 revision of this API.