Return/Refund an Order

Completed orders can be returned or refunded either fully or partially. Partial refunds are processed by specifying the particular items from the original order that need to be refunded. The total refund amount cannot exceed the original transaction amount.

Refund Types

Type	Description
Full Refund	Process a refund for the entire order amount
Partial Refund	Process a refund for specific items or a specific amount

Important Notes

During refunds, the transaction fee is charged again
For partial refunds, include only the items being refunded in the orderLines of the return order

Prerequisites

API Credentials

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

Purchase Order ID

purchaseOrderId - The orderId of the original purchase transaction

For partial refunds, you also need:

Details of items to be refunded
Item information for orderLines (name, quantity, unitPrice)

Full Refund

To process a complete refund for the entire order amount:

Create Return Order

Make a POST request to Create New Order API:

Set type as "return"
Provide the purchaseOrderId of the original purchase transaction
Include the original orderLines with the items being refunded

Initiate Refund Payment

Use the return orderId to initiate the refund payment

Example: Create Return Order

$ curl -X POST \
>   -d '{
>     "terminal$id": "8342bf45e0cef80504",
>     "type": "return",
>     "purchaseOrderId": "834952e5ac0738040b",
>     "referenceId": "RETURN-001",
>     "orderLines": [
>       {
>         "id": "1234",
>         "name": "Orange Juice",
>         "quantity": 1,
>         "itemAmount": {
>           "regular": 100,
>           "total": 100,
>           "currency": "SEK",
>           "tax": [
>             {
>               "amount": 15,
>               "percentage": 15,
>               "type": "vat"
>             }
>           ]
>         }
>       },
>       {
>         "id": "1233",
>         "name": "Grape Juice",
>         "quantity": 1,
>         "itemAmount": {
>           "regular": 100,
>           "total": 100,
>           "currency": "SEK",
>           "tax": [
>             {
>               "amount": 15,
>               "percentage": 15,
>               "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: Initiate Refund Payment

$ curl -X POST \
>   -d '{
>     "orderId": "83495a30ac0738050b",
>     "paymentMethod": "CARD_NP",
>     "refundReason": "CUSTOMER_INITIATED_RETURN"
>   }' \
>   -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'

Partial Refunds

You can create partial refunds in two ways:

Using OrderLines

Using Total Amount

Refund specific items from the original order by creating a return order with those items in the orderLines. For example, if the original order contained multiple items (apple, coke, burger), you can refund just one item (burger) by including only that item in the return order.

Required Parameters for Partial Refunds

Parameter	Type	Required	Description
`terminal$id`	string	Required	ID of the terminal processing the refund
`type`	string	Required	Must be set to `"return"`
`purchaseOrderId`	string	Required	ID of the original purchase order

Method 1: Using OrderLines

Step 1: Create a return order by specifying the items to be refunded:

$ curl -X POST \
>   -d '{
>     "terminal$id": "82e69dd73d52c80805",
>     "type": "return",
>     "purchaseOrderId": "82e89db83d0470090b",
>     "orderLines": [
>       {
>         "id": "1234",
>         "name": "Bucket hat",
>         "quantity": 1,
>         "itemAmount": {
>           "regular": 2000,
>           "total": 2000,
>           "currency": "SEK",
>           "tax": [
>             {
>               "amount": 200,
>               "percentage": 10,
>               "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'

Step 2: Initiate refund payment using the returned orderId:

$ curl -X POST \
>   -d '{
>     "orderId": "82ea625b03c9100d0b",
>     "paymentMethod": "CARD_NP",
>     "refundReason": "CUSTOMER_INITIATED_RETURN",
>     "purchasePaymentId": "8344c1bba91f580506"
>   }' \
>   -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'

purchasePaymentId is required only when the original order was paid partially, regardless of payment type. It is not required for card-present refunds.

Method 2: Using Total Order Amount

Step 1: Create a return order by specifying the refund amount directly:

$ curl -X POST \
>   -d '{
>     "terminal$id": "82e69dd73d52c80805",
>     "type": "return",
>     "purchaseOrderId": "82e89db83d0470090b",
>     "totalOrderAmount": {
>       "regular": 2000,
>       "total": 2000,
>       "currency": "SEK",
>       "tax": [
>         {
>           "amount": 200,
>           "percentage": 10,
>           "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'

orderLines is required for both purchase and return orders. The only exception is when processing a partial refund using the totalOrderAmount field — in this case, orderLines is not needed.

Step 2: Initiate refund payment using the returned orderId:

$ curl -X POST \
>   -d '{
>     "orderId": "82ea625b03c9100d0b",
>     "paymentMethod": "CARD_NP",
>     "refundReason": "CUSTOMER_INITIATED_RETURN",
>     "purchasePaymentId": "8344c1bba91f580506"
>   }' \
>   -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'

Payment Method Requirements

Refunds must be processed using the corresponding refund method for the original payment:

Original Payment	Refund Method
Card transactions	`CARD_NP` (recommended)
KLARNA	`KLARNA`
SWISH	`SWISH`
Other digital methods	Same as original transaction

Recommended: Use CARD_NP (Card Not Present) for card refunds. This processes the refund automatically without requiring the customer to tap their card on the terminal.

Check Refund Status

You can track refund status by:

Listening to webhooks for real-time updates
Using the Fetch Order Status API to check progress

Cancel a Payment

You can cancel a payment for an order if necessary, but only before the payment transfer is completed. Once the payment has been completed, you cannot cancel it directly — instead you will need to void the payment.

Prerequisites

API Credentials

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

Payment ID

paymentId from the Initiate Payment API

Cancel a Payment

Make a DELETE request to the Cancel Payment API using the paymentId:

$ curl -X DELETE \
>   -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/{paymentId}'

Response Status

Status	Description
`PAYMENT_COMPLETED`	Payment is completed and cannot be cancelled
`PAYMENT_FAILED`	Failed payments cannot be cancelled
`PAYMENT_CANCELLED`	The payment has been cancelled successfully

Void a Payment

Voiding a payment will stop the payment process before any money is moved from the customer’s account to the merchant’s account. This helps avoid issues with incorrect transactions soon after the payment is initiated.

Important

Voiding a payment is possible only before 23:00 UTC and cannot be done when the payment is not completed.

Prerequisites

API Credentials

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

Payment ID

paymentId from the Initiate Payment API

Void a Payment

Make a PUT request to the Void Payment API:

$ curl -X PUT \
>   -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/{paymentId}/void'

Void Status

Status	Description
`VOID_INITIATED`	Void is initiated (processing cancellation)
`CANNOT_VOID`	Cannot be voided (transaction not completed or exceeds void period)
`VOIDED`	Void is completed (payment cancelled)

Void vs Return/Refund

Aspect	Void	Return/Refund
Timing	Before 23:00 UTC on same day	Any time after settlement
Money Transfer	No money transferred	Money already transferred
Cardholder Present	Not required	Card present or not present
Use Case	Cancel before settlement	Return after settlement

Refund Modes

Mode	Description
Card Present Refunds	Customer is required to tap the card on the terminal
Card Not Present Refunds	Money automatically returned to the original card (recommended)