GuidesAPI ReferenceDiscussions

Capture a Klarna Payment

Suggest Edits

Overview

Every Klarna Deposit reaches the ExecutedByProvider (142) state after successful authorisation with Klarna (funds reserved but not debited yet). To capture a Klarna Deposit which is in state ExecutedByProvider (with full or partial amount), initiatePaymentFromReference needs to be used with an amount lower or equal to the (remaining) authorisation amount.

Klarna Deposit is offered as aggregation method by PXP Financial to its merchants. After capturing an amount with Klarna, Klarna will settle the money to PXP Financial and the merchant will receive the money with the regular PXP Financial merchant settlement a few days later.

Klarna (Partial) Captures can only be created if the original payment has one of the following payment methods:

  • Klarna Pay Now (370)
  • Klarna Pay Later (371)
  • Klarna Financing (372)

To trigger a full or partial capture for a Klarna payment, an intiatePaymentFromReference request using paymentMethodID = 377 ("Klarna Capture") has to be sent.

IDName
377Klarna Capture

The following table contains the fields which have to/can be sent in the initiatePaymentFromReference :

Field (value type, required)Description
amount
(positiveMoney, required)		The amount of the partial capture must be lower than or equal to the amount of the original Klarna Deposit payment and above 0. In case of multiple partial captures it must be lower than or equal to the authorised amount minus previous successful partial captures.
paymentDescription
(string, optional)		Description of the capture shown to the customer by Klarna.
Maximum 255 characters.
paymentMethodID
(positiveInt,, required)		Should contain value tbd for "Klarna Partial Capture"

Note: if preferred by a merchant, instead of initiating the capture with the the above mentioned virtual method, depending on the payment method of the original Klarna payment, the specific payment method ID for the capture payment to be created should be provided using the below table.
merchantTransactionID
(string, required)		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 partial captures of a Klarna Deposit, please contact the PXP Financial Account Developer.
originalPaymentID
(guid, required)		The paymentD 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 capture payment.
shoppingCart
(shoppingCart, optional)		Optional.
Shipped Items for this capture.
It is possible and recommended by Klarna to transmit the items which are covered with this capture request (especially in case of split shippment) to reduce customer service contacts.

Details how to structure the ShoppingCart can be found on the Klarna Deposit page.

Example initiatePaymentfromReference for capturing a Klarna Deposit with a partial amount - without shoppingCart (shipped items for this capture):

<?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://www.w3.org/2001/XMLSchema">
	<merchantID>KalixaAcceptDEMO</merchantID>
	<shopID>KalixaAcceptDEMO</shopID>
	<originalPaymentID>616129bf-3ee0-4e63-9998-2fed6e85b7b7</originalPaymentID>
	<merchantTransactionID>KlarnaCapture-00001</merchantTransactionID>
	<paymentMethodID>377</paymentMethodID>
	<amount currencyCode="GBP">30</amount>
	<specificPaymentData>				
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>Your reason for capture</value>
		</data>
	</specificPaymentData>
</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 with the following payment methods (depending on the payment method of the original Klarna payment):

IDNameSuccessful StateOriginal Klarna Payment Method
378Klarna Pay Now CapturePendingToBeCaptured (306)Klarna Pay Now (370)
379Klarna Pay Later CapturePendingToBeCaptured (306)Klarna Pay Later (371)
380Klarna Financing CapturePendingToBeCaptured (306)Klarna Financing (372)

The Klarna Capture payment will be in state PendingToBeCaptured. The capture request was not yet sent to the provider. On a daily basis, the PXP Financial system will collect all pending captures and send them to provider Klarna. They will then be in state CapturedByProvider.

📘

How to move payments to CapturedByProvider for testing

For testing purposes, this step can be done manually using the Payment Service 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

The response for the initiatePaymentFromReference request will contain all relevant data about the new payment which was created for the partial capture.

Example initiatePaymentFromReference response for successfully capturing 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>380</key>
			<value>KlarnaFinancingCapture</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>1</key>
			<value>User</value>
		</creationType>
		<userIP>195.72.132.1</userIP>
		<state>
			<id>6aab23b7-7dab-466c-ba65-5591f54a4fd8</id>
			<definition>
				<key>306</key>
				<value>PendingToBeCaptured</value>
			</definition>
			<createdOn>2014-12-12T12:28:19.6350814Z</createdOn>
      <paymentStateDetails>
         <detail xsi:type="keyStringValuePair">
             <key>PaymentStateReasonID</key>
             <value>1</value>
         </detail>
      </paymentStateDetails>   
    </state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">37.89</baseAmount>
		<paymentDetails>
            <detail xsi:type="keyIntValuePair">
                <key>OriginalPaymentID</key>
                <value>1764960</value>
            </detail>
    </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
	</payment>
</initiatePaymentFromReferenceResponse>
FieldValueDescription
payment.paymentIDsome GUIDThe ID of the new Klarna partial capture payment which was created.
payment.state.definition306
(PendingToBeCaptured)		The state of the new Klarna partial capture payment.
payment.paymentMethodID378
(Klarna Pay Now Capture)
or
379
(Klarna Pay Later Capture)
or
380
(Klarna Financing Capture)		The payment method ID of the new Klarna partial capture payment.

Example initiatePaymentFromReference response for an unsuccessful Klarna capture request:

<paymentServiceException xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <id>e3432708-02cd-4b3e-815c-fa4b61de4e19</id>
    <errorCode>100</errorCode>
    <errorMessage>The capture amount 4,02 GBP must be less or equal to the remaining capturable amount: 4,0100 GBP.</errorMessage>
</paymentServiceException>

Example initiatePaymentfromReference for capturing a Klarna Deposit - with shoppingCart (shipped items for this capture):

<?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>KlarnaCapture-00001</merchantTransactionID>
    <paymentMethodID>377</paymentMethodID>
    <amount currencyCode="sek">110.00
    </amount>
    <specificPaymentData>               
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>Your reason for capture</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>

Payment State Flow for all Klarna PartialCapture payments:

581

Errors

If a (partial) capture cannot be done due to invalid data (e.g. unknown originalPaymentID) the following error codes are returned:

Error CodeError messageDescription
100The capture PaymentMethod [KlarnaPayLaterCapture or KlarnaPayNowCapture or KlarnaPayLaterCapture] is not compatible with the Klarna Deposit PaymentMethod [KlarnaPayNowDeposit]. Please use the common capture payment method [KlarnaCapture]Unsuccessful initiation of a capture payment due to unmatched original payment method id.
100The capture amount 20.01 GBP must be less or equal to the remaining capturable amount: 20.0000 GBP.Unsuccessful initiation of a capture payment due to invalid amount
100The capture amount 10.02 GBP must be less or equal to the remaining capturable amount: 10.0100 GBP.Unsuccessful initiation of a capture payment due to invalid amount (with an already existing successful partial capture)
100The currency EUR of the capture payment must be equal to the currency GBP of the Klarna Deposit Payment [UniqueID=$$OriginalUniqueID$$].Unsuccessful initiation of a capture payment due to unexpected payment state of the original payment
209Payment with PaymentID '00000000-0000-0000-0000-000000000001' was not found.Unsuccessful initiation of a capture payment due to non existing original id

📘

Generic Error Codes

Find here more information about Error Handling and generic error codes.

Cancellation of Partial Capture Payments

Cancellations of Card Partial Capture Payments are not allowed. Corrections need to be done using functionality to Refund a Klarna Payment.

Multiple Partial Capture - Split Shipment

It is possible to partially capture a Klarna payment multiple times, up to the original authorisation amount.

To capture a Klarna payment multiple times (e.g. in case of a split shipment), initiatePaymentFromReference needs to be used with an amount lower or equal to the remaining authorisation amount.

In case the merchant is not intending to capture the whole authorised amount, the remaining amount should be cancelled after all partial captures were successfully initiated with PXP Financial.
With this, merchants can ensure that their customers are not negatively impacted by extended authorization holds against their accounts and that the money can be used for other purchases.

Information how to release the remaining authorisation amount for a Klarna Deposit can be found here: Cancel/Revert a Klarna Payment

❗️

All captures need to be sent before remaining amount is released

No further partial capture request will be accepted for the original Klarna payment once a cancellation request to revert the remaining amount was sent.

How to test Klarna (Partial) Captures

Updated over 3 years ago