Online Refunds

Refunds for online transactions are processed as Card Not Present (CNP) refunds. You can process either full refunds or partial refunds for specific items in an order. This guide explains how to initiate these refunds and check their status using the API or merchant portal.

Prerequisites

API credentials
purchaseOrderId - The orderId of the original purchase transaction that you want to refund
For partial refunds:
- Details of specific items to be refunded
- Item information for orderLines (name, quantity, unitPrice)

Types of Refunds

Full Refund

Process a complete refund for the entire order amount.

Partial Refund

You can create partial refunds in two ways:

Method	Description
Using OrderLines	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.
Using Total Amount	Specify the refund amount directly without itemizing products by including the `totalOrderPrice` in your return order. This is useful when you don’t need to track which specific items are being refunded.

Initiate Online Refund

To initiate an online refund, use the CNP refund method provided in the Initiate Payment API.

Create Return Order

Make a POST request to the Create New Order API with the following key parameters:

Parameter	Description
`terminal$id`	Identify the terminal from which you’re creating the order
`purchaseOrderId`	The Order ID (`orderId`) of the order to be returned or refunded
`type`	Specify the order type as `return`

Initiate Refund Payment

Use the return orderId received from Step 1 to initiate the refund payment

Step 1: Create Return Order

$ curl -d '{
>     "terminal$id": "8342bf45e0cef80504",
>     "type": "return",
>     "purchaseOrderId": "834952e5ac0738040b",
>     "referenceId": "orderabc",
>     "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' \
>   YOUR_API_URL/orders

Step 2: Initiate Refund Payment

Use the return orderId received from Step 1:

$ curl -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' \
>      YOUR_API_URL/payments

Refund Reason Codes

Parameter	Description
`CUSTOMER_INITIATED_RETURN`	When a customer initiates a return of a product or service they purchased
`SUSPECTED_MALFUNCTION`	When there is a suspected system malfunction
`SUSPECTED_FRAUD`	When there is suspected irregularity/fraud
`DUPLICATE_TRANSACTION`	When there are duplicate transactions noticed in the system
`OTHER`	For refund requests that do not fit into the specific categories mentioned above

When using OTHER as the refundReason, you must provide an otherReason parameter describing the reason for the return request.

Partial Refunds

Method 1: Using OrderLines

Create a return order by specifying the items to be refunded. The total refund amount will be automatically calculated based on the orderLines.

OrderLines Parameters:

Parameter	Description
`id`	Unique identifier for the order line (e.g., “1234”)
`name`	Product name (e.g., “Burger”)
`quantity`	Number of items (e.g., 1)
`itemAmount.regular`	Regular price of the product in the smallest currency unit (e.g., 2000)
`itemAmount.total`	Total amount payable by the customer per unit in smallest currency units (e.g., 2000)
`itemAmount.currency`	Type of currency in ISO 4217 format (e.g., “SEK”)
`itemAmount.tax`	Array of tax objects

Step 1: Create Return Order with OrderLines

$ curl -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' \
>      YOUR_API_URL/orders

Step 2: Initiate Refund Payment

$ curl -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' \
>      YOUR_API_URL/payments

Note

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

Create a return order by specifying the refund amount directly.

TotalOrderAmount Parameters:

Parameter	Description
`regular`	Regular price of the order in the smallest currency unit (e.g., 2000)
`total`	Actual amount that the customer has to pay in the smallest currency unit (e.g., 2000)
`currency`	Type of currency in ISO 4217 format (e.g., “SEK”)
`tax`	Array of tax objects

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 1: Create Return Order with Total Amount

$ curl -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' \
>      YOUR_API_URL/orders

Step 2: Initiate Refund Payment

$ curl -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' \
>      YOUR_API_URL/payments

Payment Method for Refunds

Important

Refunds must be processed using the corresponding payment method used in the purchase transaction.

Original Payment	Refund Payment Method
Card transactions	`CARD_NP`
Klarna	`KLARNA`
Other digital payment methods	Same as original transaction

Check Refund Status

You can listen to the webhook to receive status of the refund or check its status using the Fetch Order Status API. This API allows you to track the progress of your refund request.