Capture Card Pre-Authorisations

Overview

Every Card Pre-Authorisation reaches the AuthorisedByProvider (13) state after successful authorisation (funds reserved but not debited yet). To capture a card pre-authorisation which is in state AuthorisedByProvider (with full or partial amount), executePaymentAction with actionID = 154 (Partially Capture) needs to be used with an amount lower or equal to the pre-authorisation amount.

Partial Capture requests are only applicable for the following payment methods:

  • Mastercard PreAuthorisation (304)
  • Visa Estimated Authorisation (305)
  • Visa MultiCapture Authorisation (311)

The following table contains the fields which have to/can be sent in the actionData xml section of the executePaymentAction:

🚧

Amount

Effective as of November 7th, 2018 the value type of the Amount key will be changed from string to decimal.

key (value type, required)

value

Amount
(decimal, required)

The amount of the partial capture must be lower than or equal to the amount of the original pre-authorisation payment and above 0.

PaymentDescription
(string, optional)

The value of this field is stored as payment description on the partial capture payment.
If no value is sent for this field, the payment description which was transmitted in the original pre-authorisation will be used as payment description by default.

Note: In case dynamic descriptors are activated for the merchant, the value of this field is NOT used as descriptor. The value from the original Card Pre-authorisation payment is used and shown on the card holders statement.

IsFinalPartialCapture
(boolean, optional)

It is possible to indicate within a Partial Capture request that this will be the last partial capture and the remaining amount can be reverted.

If IsFinalPartialCapture is set to true, the PXP Financial System will automatically revert the remaining authorised amount with the Issuer.

If no value provided or false, the remaining pre-authorised amount will be kept reserved and further partial captures can be done.

In case of Visa Estimated Authorisation (305), this parameter is not relevant, as no multiple partial captures are allowed for this payment method (IsFinalPartialCapture is set to true by default).

🚧

IsFinalPartialCapture

It is the merchants responsibility to indicate to PXP Financial that a particular partial capture will be the final/last so that the PXP Financial System can automatically revert the remaining authorised amount with the Issuer (if an amount is remaining).

The merchant must do this by setting IsFinalPartialCapture to true in the partial capture request (see above)

With this, merchants can ensure that cardholders are not negatively impacted by extended authorization holds against their accounts and that the money can be used for other purchases.

Example executePaymentActionRequest for capturing a card pre-authorisation with a partial amount:

📘

paymentID

The field paymentID must contain the ID of the original pre-authorisation payment for which the partial capture request is sent.

<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
                      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">          
  <merchantID>KalixaAcceptDEMO</merchantID>
  <shopID>KalixaAcceptDEMO</shopID>
  <paymentID>684e2d61-b0aa-4e2f-bc21-afd8f9287f93</paymentID>
  <actionID>154</actionID>
  <actionData>
    <data xsi:type="keyDecimalValuePair">
       <key>Amount</key>
       <value>90</value>
    </data>
    <data xsi:type="keyBooleanValuePair">
       <key>IsFinalPartialCapture</key>
       <value>true</value>
    </data>
  </actionData>
</executePaymentActionRequest>

The card pre/estimated/multicapture authorisation payment for which the executePaymentAction request was sent will remain in state AuthorisedByProvider (13). A new payment which is linked to the original card authorisation will be created with one of the following payment methods (depending on the original pre-auth payment method):

ID

Name

Successful State

Original Pre-Authorisation Payment Method

306

Mastercard PartialCapture

PendingToBeCaptured (306)

Mastercard PreAuthorisation (304)

307

Visa PartialCapture

PendingToBeCaptured (306)

Visa Estimated Authorisation (305)
Visa MultiCapture Authorisation (311)

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

Example executePaymentActionResponse for capturing a card pre-authorisation partially:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <statusCode>0</statusCode>
    <actionResults>
        <result xsi:type="keyStringValuePair">
            <key>lastStateDefinition</key>
            <value>13</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.paymentID</key>
            <value>43f91041-035e-4b50-86d6-2f5f4e5d486a</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.lastStateDefinition</key>
            <value>306</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.paymentMethodID</key>
            <value>306</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

Details for actionResults:

key

value

Description

lastStateDefinition

13
(AuthorisedByProvider)
or
577
(Completed)

The last state of the original pre-authorisation payment for which the partial capture request was sent.

  • 13 AuthorisedByProvider (if further partial captures are possible on this payment)
  • 577 Completed (if no further partial captures are possible on this payment)

createdPayment.paymentID

some GUID

The ID of the new partial capture payment which was created.

createdPayment.lastStateDefinition

306
(PendingToBeCaptured)

The state of the new partial capture payment.

createdPayment.paymentMethodID

306
(Mastercard PartialCapture)
or
307
(Visa PartialCapture)

The payment method ID of the new partial capture payment.

Payment Flow for Mastercard PartialCapture (306) and Visa PartialCapture (307) payments:

Errors

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

Error Code

Error Message Example

Description

700

Error Message: The action is not allowed for the payment.

There are 2 possible reasons for this error:

  • The original pre-authorisation payment is not in a correct state. It has to be in state AuthorisedByProvider
  • The original payment is not a pre-authorisation, so a partial capture request for this payment is not allowed.

1037

Error Message: Error creating payment: The amount must be greater than 0.

There are 2 possible reasons for this error:

  • The actionData.amount Field was not provided in the request.
  • The actionData.amount vlaue was zero.

1037

Example Error Message: Amount for partial capture payment must be less or equal to the remaining authorised amount [Money - Amount: 0.9900, Currency[ID=2, Code=EUR, Exponent=2]].

The amount of the partial capture is higher than the amount of the original payment.

500

Error Message: Internal server error.

PaymentID must be a GUID.

800

Missing field paymentID.

209

Example Error Message: Payment with PaymentID 'e03964e8-dd2e-417b-a908-ecfdc4d46bf9' was not found.

Unknown paymentID.

Cancellation of Partial Capture Payments

Cancellations of Card Partial Capture Payments are not allowed. Corrections need to be done using refunds.

Refund a Partial Capture Payment

To refund a partial capture, the Card Refunds functionality must be used.
The createdPayment.paymentID of the partial capture payment (received in the executePaymentActionResponse for capturing a card pre-authorisation) must be used as originalPaymentID in the initiatePaymentFromReferenceRequest.

Partial refunds are also supported for Partial Capture payments.

🚧

Refunds applicability

Refunds can only be done on a partial capture payment. They cannot be done on the original Pre-Authorisation payment.

Multiple Partial Capture - Split Shipment

🚧

Multiple Partial Capture (Split Shipment)

The Multiple Partial Capture (Split Shipment) functionality for Mastercard PreAuthorisation and Visa MultiCapture Authorisation has been released on the PXP Live-Environment on October 10th 2019.

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

Multiple Partial Captures are only applicable for the following payment methods:

  • Mastercard PreAuthorisation (304)
  • Visa MultiCapture Authorisation (311)

To capture a card pre-authorisation multiple times (e.g. in case of a split shipment), executePaymentAction with actionID = 154 (Partially Capture) needs to be used with an amount lower or equal to the remaining pre-authorisation amount.

If a partial capture is the last/final one, the optional parameter IsFinalPartialCapture should be sent as true. PXP Financial will then automatically revert the remaining amount (where applicable) with the Issuer.
Notes:

  • no further partial capture request will be accepted for the original pre-authorisation once a partial capture with IsFinalPartialCapture = true has been sent.
  • The last state of the original pre-authorisation payment for which the partial capture request was sent will change to Completed (577).

How to handle Refunds in case of Multiple Partial Capture/Split Shipment

Refunds need to be done for each partial capture separately using the createdPayment.paymentID of the partial capture payment (received in the executePaymentActionResponse for capturing a card pre-authorisation).
It is not possible to create refunds with specific amounts directly on the pre-authorisation.

📘

Remaining pre-authorisation amount

The remaining pre-authorisation amount which could be captured still does not increase because of a refund.

Example 1: Refunding Multiple partial captures with IsFinalPartialCapture = true

  • merchant makes a Pre-authorisation for 100 EUR
  • merchant executes 1st partial capture for 50 EUR (with IsFinalPartialCapture = false)
  • merchant executes 2nd partial capture for 20 EUR (with IsFinalPartialCapture = false)
  • merchant executes 3rd partial capture for 10 EUR (with IsFinalPartialCapture = true)
    (remaining authorisation amount of 20 EUR will be reverted with the schemes and will be available on the customer card; they cannot be captured anymore)

If the merchant wants to refund for example 55 EUR he has to refund the relevant partial captures separately. For example:

  • merchant initiates a refund 50 EUR for 1st partial capture
  • merchant initiates a refund 5 EUR for 2nd partial capture

(or any other possible combination)

Example 2: Refunding Multiple partial captures with IsFinalPartialCapture = false

  • merchant makes a Pre-authorisation for 100 EUR
  • merchant executes 1st partial capture for 50 EUR (with IsFinalPartialCapture = false)
  • merchant executes 2nd partial capture for 20 EUR (with IsFinalPartialCapture = false)
    (remaining authorisation amount: 30 EUR which could be captured still)
  • merchant initiates a refund of 2nd partial capture with 15 EUR (partial amount) --> remaining refundable amount for 2nd partial capture is 5 EUR
    (Note: the remaining authorisation amount of 30 EUR which could be captured still does not change because of the refund)
  • merchant initiates a refund of 1st partial capture with 50 EUR (=full amount) --> no remaining refundable amount for 1st partial capture
    (Note: the remaining authorisation amount of 30 EUR which could be captured still does not change because of the refund)
  • merchant executes 3rd partial capture for 25 EUR (with IsFinalPartialCapture = true)
    (remaining authorisation amount of 5 EUR will be reverted with the schemes and will be available on the customer card; they cannot be captured anymore)

Remaining refundable amounts:

  • 5 EUR for 2nd partial capture
  • 0 EUR for 1st partial capture
  • 25 EUR for 3rd partial capture

Remaining pre-authorisation amount (which could be captured still): 0 EUR