GuidesAPI ReferenceDiscussions

Cancel/Revert a PayPal Pre-Authorisation

Suggest Edits

🚧

This page is about the PayPal V2 integration

For information on PayPalExpressCheckoutDeposit see here.


Overview

If the merchant is not intending to complete the authorised PayPal payment and therefore no longer requires the amount to be held, the PayPal payment should be cancelled to free up the available purchase amount for this customer at PayPal. This is especially important if the customer has used a card in his purchase flow.

PayPal (Partial) Cancellation requests are only applicable for the following payment methods:

  • PayPal Reference PreAuthorisation (396)
  • PayPal Redirect PreAuthorisation (395)

📘

PayPal Deposit methods cannot be cancelled

Payments using the PayPal Reference Deposit (393) and the PayPal Redirect Deposit (394) payment method are intended to be immediately captured with PayPal and can therefore not be cancelled. If they need to be reverted, then a refund must be created.

Two different use-cases are supported:

  1. Full cancellation
    Applies if the PayPal Deposit has not yet been (partially) captured. The full authorisation amount will be cancelled with PayPal.
  2. Release the remaining authorisation amount (partial cancellation)
    Applies if at least one successful partial capture has been done already. The remaining authorised amount will be cancelled with PayPal. No further captures will be possible.

❗️

All captures need to be sent before remaining amount is released

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

How to cancel/revert or release the remaining amount for a PayPal Payment

A PayPal payment can be cancelled by using the executePaymentAction with actionID = 1 (Cancel). Any amount sent in this request will be ignored and the remaining or full authorisation amount is reverted.

In the case of a cancellation of a PayPal payment, the original PayPal payment remain in state ExecutedByProvider (142).

Example executePaymentActionRequest for a cancellation of a PayPal payment:

<?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-afd8f9287f94</paymentID>
  <actionID>1</actionID>
</executePaymentActionRequest>

A new payment which is linked to the original PayPal payment will be created with the following payment method:

IDPayment Method NameSuccessful State
429PayPal CancellationCancelled (113)

The response for the executePaymentAction request will contain all relevant data about the new cancellation payment which was created for the cancellation/reversal.

Example executePaymentActionResponse for a full cancellation of a PayPal payment:

<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>142</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.paymentID</key>
            <value>f6450056-9889-4fb0-bd98-5b4a795c475b</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.lastStateDefinition</key>
            <value>113</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.paymentMethodID</key>
            <value>429</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderTransactionID</key>
            <value>3VS741692R874921K</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderAuthorizationID</key>
            <value>21Y59180JK9410504</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderResponseCode</key>
            <value>0</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

Details for actionResults:

FieldValueDescription
lastStateDefinition142
(ExecutedByProvider)		The last state of the original PayPal Deposit payment for which the cancel request was sent.
createdPayment.paymentIDsome GUIDThe ID of the new cancellation payment which was created.
createdPayment.lastStateDefinition113
(Cancelled)
This is the successful state.
or
260
(CancelRefusedByProvider)
or
349
(CancelCommunicationErrorOccurred)		The state of the new cancellation payment.
createdPayment.paymentMethodID429
(PayPal Cancellation)		The payment method ID of the new cancellation payment.

Example executePaymentActionResponse for a cancellation request of a PayPal payment which was refused by the provider (PayPal):

<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>142</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.paymentID</key>
            <value>3132a0b3-c93f-4d55-a396-a63e01ef236d</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.lastStateDefinition</key>
            <value>260</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>createdPayment.paymentMethodID</key>
            <value>429</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderTransactionID</key>
            <value>D9FFE800-89DF-41D0-AFC3-58C47DAC3370</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

Payment Flow for PayPal Cancellation payments:

Errors

PXP Financial Payment Service will return a paymentServiceException message in case an unexpected error occurs when initiating a PayPal Deposit payment.

📘

Generic Error Codes

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

If the cancellation request was refused due to a validation error, the following error code is returned and the message will explain the problem:

Error CodeError Message
100A general validation error occurred. For details see message field of the paymentServiceException

Example paymentServiceException message for an invalid cancellation payment request for a PayPal payment:

<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>c3962c91-43fe-4d25-b383-9f5c2da927cc</id>
    <errorCode>100</errorCode>
    <errorMessage>There is no authorized amount left to cancel.</errorMessage>
</paymentServiceException>

Cancellation initiated via PXP Admin or via Paypal Account (not triggerd by merchant system)

It is possible, that Paypal Pre-authorisations are cancelled by an operator via the PXP Admin or the Paypal account. In this case, the PXP system

  • cancels the pre-authorisation (=create a cancel payment)
  • notifies the merchant (The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about created cancellation payment. For more information see PaymentStateChangedNotification. )

Example handlePaymentStateChangedNotificationRequest for a full cancellation of a PayPal payment:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
  <payment xmlns:q1=http://www.cqrpayments.com/PaymentProcessing xsi:type="paymentWithPaymentAccount">
    <merchantID>PayPalRestAPIProviderTesting<merchantID>
    <shopID>PayPalRestAPIPTShop1<shopID>
    <paymentMethod>
      <key>429<key>
      <value>PayPal Cancellation<value>
    <paymentMethod>
    <merchantTransactionID>2GS133397D318625X<merchantTransactionID>
    <paymentID>4f1aa9e1-faf8-4194-81ef-6f62119ac44e<paymentID>
    <userID>8eb5ae57-2d13-4d64-9245-41d583<userID>
    <paymentProvider>
      <key>56<key>
      <value>PayPal<value>
    <paymentProvider>
    <amount currencyCode="EUR">110.0000<amount>
    <creationType>
      <key>6<key>
      <value>Provider<value>
    <creationType>
    <userIP>80.121.151.158<userIP>
    <state>
      <id>9cb8e41c-acea-47a0-9997-c2a0ba7d4139<id>
      <definition>
        <key>113<key>
        <value>Cancelled<value>
      <definition>
      <createdOn>2022-03-29T15:45:48.08<createdOn>
      <paymentStateDetails xsi:nil="true" />
    <state>
    <isExecuted>true<isExecuted>
    <baseAmount currencyCode="EUR">110.0000<baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID<key>
        <value>40901032<value>
      <detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderAuthorizationID<key>
        <value>2GS133397D318625X<value>
      <detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentID<key>
        <value>c0f579e7-2675-496d-8fbe-c24a6456e09f<value>
      <detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMerchantTransactionID<key>
        <value>hc-20220329-174453<value>
      <detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodID<key>
        <value>396<value>
      <detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName<key>
        <value>PayPal Reference PreAuthorisation<value>
      <detail>
    <paymentDetails>
    <paymentAccount>
      <paymentAccountID>0<paymentAccountID>
    <paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>

How to test PayPal Cancellation

  • Test-Cases applicable for PayPal Cancellation: Test cases
  • Information how to cancel a PayPal Deposit payment manually using the PXP Admin tool: Test cases

Cancel a Paypal Pre-Auth via PXP Admin Tool

It is also possible to cancel a PayPal Pre-auth via PXP Payment Service Admin tool.

Cancel a Paypal Pre-Auth via the merchants PayPal Account.

It is also possible to cancel a PayPal Pre-auth via the merchant PayPal account.

Updated 4 days ago