Refund a payment

See Knowledge base: Refunds for a general introduction to refunds.

A Refund will reverse the direction of a transaction and move money from the Merchant back to the customer.

Refunds can be made in full or partially as needed. The refund amount must be defined in the refund API request.

Refunded funds will be deducted from the merchant's settlement account after two business days. See Settlement Information for more details.

Full refund

If a customer has returned the goods or the service is not delivered, you should refund the payment. This can be done through the refund endpoint.

For example, if the amount you have captured is 499,00 NOK, and you want to refund the whole amount (499,00 NOK):

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "modificationAmount": {
    "currency": "NOK",
    "value": 49900
  }
}'

In the response, the aggregate object will be updated to reflect the refunded amount. Here you see that you have refunded 499,00 NOK of the originally captured amount, 499,00 NOK.

{
  "aggregate": {
    "authorizedAmount": {
      "currency": "NOK",
      "value": 49900
    },
    "cancelledAmount": {
      "currency": "NOK",
      "value": 0
    },
    "capturedAmount": {
      "currency": "NOK",
      "value": 49900
    },
    "refundedAmount": {
      "currency": "NOK",
      "value": 49900
    }
  }
}

A notification will also be sent once the refund is completed if a webhook is registered for the event epayments.payment.refunded.v1.

To learn more about refunds, see Knowledge base: Refunds.

Partial refund

If you don't want to refund the entire amount, a smaller amount than captured can be refunded. This can be done multiple times.

The Idempotency-Key header is there to help you ensure at most once operation where needed.

For example, if the amount you have captured is 499,00 NOK, and you want to refund 100,00 NOK:

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "modificationAmount": {
    "currency": "NOK",
    "value": 10000
  }
}'

In the response, you see that you have refunded 100,00 NOK of the originally captured amount, 499,00 NOK. Then, you know that you have 399,00 NOK remaining to refund (i.e., capturedAmount.value - refundedAmount.value). You can also check the event log endpoint.

{
  "aggregate": {
    "authorizedAmount": {
      "currency": "NOK",
      "value": 49900
    },
    "cancelledAmount": {
      "currency": "NOK",
      "value": 0
    },
    "capturedAmount": {
      "currency": "NOK",
      "value": 49900
    },
    "refundedAmount": {
      "currency": "NOK",
      "value": 10000
    }
  }
}

To learn more about partial refund, see Knowledge base: Partial refund.

Partial refund after partial capture

During a partial capture, you authorize an amount and capture only a part of this.

To refund and clear this charge, you refund the amount you have captured and then cancel the payment.

For example, if the amount you have authorized is 499,00 NOK, and have captured 100,00 NOK. First, refund the 100,00 NOK:

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
  "modificationAmount": {
    "currency": "NOK",
    "value": 10000
  }
}'

In the response, you see that you have refunded all of the originally captured amount (i.e., capturedAmount.value - refundedAmount.value).

{
  "aggregate": {
    "authorizedAmount": {
      "currency": "NOK",
      "value": 49900
    },
    "cancelledAmount": {
      "currency": "NOK",
      "value": 0
    },
    "capturedAmount": {
      "currency": "NOK",
      "value": 10000
    },
    "refundedAmount": {
      "currency": "NOK",
      "value": 10000
    }
  }
}

Second, cancel the payment:

curl -X POST https://apitest.vipps.no/epayment/v1/payments/UNIQUE-PAYMENT-REFERENCE/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d ''

The response shows:

   "aggregate": {
        "authorizedAmount": {
            "currency": "NOK",
            "value": 1995
        },
        "cancelledAmount": {
            "currency": "NOK",
            "value": 995
        },
        "capturedAmount": {
            "currency": "NOK",
            "value": 1000
        },
        "refundedAmount": {
            "currency": "NOK",
            "value": 1000
        }

The event log shows progression of steps.

note

The payment state returned by getPayment will show AUTHORIZED even though the payment has been refunded.

To learn more about partial capture, see Knowledge base: Partial capture.