To initiate a refund for a Klarna payment, the initiatePaymentFromReference API call must be used.
Klarna (Partial) Refund requests are only applicable for the following payment methods:
- Klarna Pay Now (370)
- Klarna Pay Later (371)
- Klarna Financing (372)
Capture payments must be in state
Refunds can only be done for Klarna payments which were already captured with provider Klarna (Capture payments must be in state
For testing purposes, Klarna Capture payments can be manually moved from state
CapturedByProviderusing the PXP Financial Admin Tool. Instructions how to manipulate a Klarna capture payment for testing purposes using the PXP Admin tool can be found here: Capture Testing FAQs
paymentID of the original Klarna payment (received in the
initiatePaymentResponse for initiating a new Klarna payment) must be used as
originalPaymentID in the
initiatePaymentFromReferenceRequest for creating the refund.
The merchant can decide to refund the full or a partial amount - but it must sum up to the total captured amount of the Klarna payment.
To trigger a refund for a Klarna payment, an intiatePaymentFromReference request using paymentMethodID = 376 ("Klarna Refund") has to be sent.
The following table contains the fields which have to/can be sent in the initiatePaymentFromReference :
|Field (value type, required)||Description|
|The amount of the refund must be lower than or equal to the total captured amount of the original Klarna Deposit payment and above 0. In case of partial refunds it must be lower than or equal to the total captured amount minus previous successful refunds.|
|Description of the refund shown to the customer by Klarna.|
Maximum 255 characters.
|Should contain value 376 for the "Klarna Refund" payment method.|
|Merchant’s transaction ID (order ID, purchase ID, sale ID ...). This ID will be shown as "PaymentID" in the merchants settlement report generated by PXP Financial and can be used for mapping/reconciliation purpose in the merchant system if applicable.|
This ID must be unique per payment to allow for idempotency. If a merchant requires/wants to to send the same merchantTransactionID for refunds of a Klarna Deposit, please contact the PXP Financial Account Developer.
List of returned items relevant for this refund.
It is possible and recommended by Klarna to transmit the items which are covered with this refund request to reduce customer service contacts.
Details how to structure the
Remaining authorised amount
The remaining authorisation amount which could be captured still does not increase because of a refund.
initiatePaymentfromReference for refunding a Klarna Deposit with a partial amount, including the optional ShoppingCart element
<?xml version="1.0" encoding="utf-8"?> <initiatePaymentFromReferenceRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http<initiatePaymentFromReferenceRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <merchantID>KalixaAcceptDEMO</merchantID> <shopID>KalixaAcceptDEMO</shopID> <originalPaymentID>616129bf-3ee0-4e63-9998-2fed6e85b7b7</originalPaymentID> <merchantTransactionID>KlarnaRefund-00001</merchantTransactionID> <paymentMethodID>376</paymentMethodID> <amount currencyCode="sek">110.00 </amount> <specificPaymentData> <data xsi:type="keyStringValuePair"> <key>PaymentDescription</key> <value>Your reason for refund</value> </data> </specificPaymentData> <shoppingCart> <items> <item> <product> <id>123456</id> <name>Jeans</name> <description>stonewashed</description> <unitPrice> <grossAmount>30</grossAmount> <taxAmount rate="20" name="VAT">5.00</taxAmount> </unitPrice> </product> <quantity>1</quantity> <totalPrice> <grossAmount>15</grossAmount> <taxAmount rate="20" name="VAT">2.5</taxAmount> </totalPrice> <discount> <name>Jeans-Promotion</name> <grossAmount>-15</grossAmount> <taxAmount rate="20" name="VAT">-2.50</taxAmount> </discount> </item> <item> <product> <id>456</id> <name>Skirt</name> <description>Flowers Design</description> <unitPrice> <grossAmount>40</grossAmount> <taxAmount rate="10" name="VAT">3.64</taxAmount> </unitPrice> </product> <quantity>2</quantity> <totalPrice> <grossAmount>75</grossAmount> <taxAmount rate="10" name="VAT">6.82</taxAmount> </totalPrice> <discount> <name>Spring-Promotion</name> <grossAmount>-5</grossAmount> <taxAmount rate="10" name="VAT">-0.45</taxAmount> </discount> </item> </items> <subTotalAmount>90</subTotalAmount> <shippingCost> <name>Express</name> <grossAmount>30</grossAmount> <taxAmount rate="20" name="VAT">5</taxAmount> </shippingCost> <discounts> <discount> <name>Sommer Sales-Discount</name> <grossAmount>-10</grossAmount> <taxAmount rate="20" name="VAT">-1.67</taxAmount> </discount> </discounts> <amountsByTax> <amountByTax taxName="VAT" taxRate="10"> <grossAmount>75</grossAmount> <taxAmount>6.82</taxAmount> </amountByTax> <amountByTax taxName="VAT" taxRate="20"> <grossAmount>35</grossAmount> <taxAmount>5.83</taxAmount> </amountByTax> </amountsByTax> <totalAmount>110</totalAmount> <totalTaxAmount>12.65</totalTaxAmount> </shoppingCart> </initiatePaymentFromReferenceRequest>
The Klarna payment for which the initiatePaymentFromReference request was sent will remain in state
ExecutedByProvider (142). A new payment which is linked to the original Klarna payment will be created.
The response for the initiatePaymentFromReference request will contain all relevant data about the new payment which was created for the refund.
initiatePaymentFromReference response for refunding a Klarna payment (partially):
<?xml version="1.0" encoding="utf-8"?> <initiatePaymentFromReferenceResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <payment xsi:type="paymentWithPaymentAccount"> <merchantID>KalixaAcceptDEMO</merchantID> <shopID>KalixaAcceptDEMO</shopID> <paymentMethod> <key>376</key> <value>KlarnaRefund</value> </paymentMethod> <merchantTransactionID>20141211_1</merchantTransactionID> <paymentID>7facb804-6ee0-4a0e-9df9-55e7f8233dac</paymentID> <userID>KalxiaTestUser_3</userID> <paymentProvider> <key>189</key> <value>Klarna</value> </paymentProvider> <amount currencyCode="GBP">30</amount> <creationType> <key>2</key> <value>MerchantOperator</value> </creationType> <userIP>22.214.171.124</userIP> <state> <id>6aab23b7-7dab-466c-ba65-5591f54a4fd8</id> <definition> <key>125</key> <value>Refunded</value> </definition> <createdOn>2014-12-12T12:28:19.6350814Z</createdOn> <paymentStateDetails xsi:nil="true"/> </state> <isExecuted>true</isExecuted> <baseAmount currencyCode="EUR">37.89</baseAmount> <paymentDetails> <detail xsi:type="keyIntValuePair"> <key>OriginalPaymentID</key> <value>1764970</value> </detail> </paymentDetails> </payment> </initiatePaymentFromReferenceResponse>
Payment State Flow for all Klarna Partial Refund payments:
If a refund cannot be done due to invalid data (e.g. unknown
originalPaymentID) the following error codes are returned:
|504||Missing field||Not all required fields necessary for specific payment method have been sent.|
e.g. amount or PaymentDescription (mandatory for refunds)
|1002||Invalid refund amount||There are 2 possible reasons for this error:|
The amount of the refund is higher than the amount of the original payment
The amount of the refund is higher than the allowed refundable amount (calculated as [original payment amount] - sum [all partial refunds])
|1003||Original payment is refundable / not in a refundable state||Refund not possible|
|1004||Invalid payment method||The specified refund payment method ID is not allowed for the original deposit’s payment method.|
Generic Error Codes
Find here more information about Error Handling and generic error codes.
It is possible to create refunds for Klarna payments with specific amounts directly on the original Klarna Deposit payment - and not for each partial capture separately.
Example : Refunding Multiple partial captures
- merchant makes a Klarna Deposit for 100 EUR
- merchant executes 1st partial capture for 50 EUR
- merchant executes 2nd partial capture for 20 EUR
- merchant executes 3rd partial capture for 10 EUR
- merchant sends cancel request to revert the remaining 20 EUR (they cannot be captured anymore)
If the merchant wants to refund for example 55 EUR he simply has to initiate one refund referencing the PaymentID of the original Klarna Deposit.
If more refunds are necessary later, another refund request, e.g. with 25 EUR can be initiated.
In total, 55 + 25 = 80 EUR were refunded now and no further refund would be possible because the total captured amount is 50 + 20 + 10 = 80 EUR.
Updated almost 3 years ago