GuidesAPI ReferenceDiscussions
Guides

Refund for PayPal Pre-Authorisation

Suggest Edits

🚧

This page is about the PayPal V2 integration

For information on PayPalExpressCheckoutDeposit see here.


To initiate a refund for a captured PayPal Pre-Authorisation payment ( PayPal Reference PreAuthorisation and PayPal Redirect PreAuthorisation, the merchant has two options:

  • Option 1: Send a refund request directly for each PayPal Capture payment separately, using the initiatePaymentFromReference API call with the PaymentID of the original related PayPal Capture payment
  • Option 2: Send a refund request based on the original PayPal Pre-Authorisation payment using the executePaymentAction API Call with actionID= 114 (“CreateRefund”)

This section is applicable for sending PayPal (Partial) Refund requests for the following payment methods:

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

Option 1: Refund directly the Capture payments for a PayPal Reference or Redirect Pre-Authorisation

With this option, the merchant has to refund a Paypal Capture payment up to the total amount of the Capture.

The paymentID of the of the original related PayPal Capture 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 a maximum of the total captured amount of the PayPal payment.

IDName
400PayPal Refund

To trigger a refund for a PayPal Capture payment, an intiatePaymentFromReference request using paymentMethodID = 400 ("PayPal Refund") has to be sent.

📘

Capture payments must be in state CapturedByProvider

Refunds can only be done for PayPal payments which were already captured with provider Klarna (Capture payments must be in state CapturedByProvider).
For testing purposes, PayPal Capture payments can be manually moved from state PendingToBeCaptured to CapturedByProvider using the PXP Financial Admin Tool.

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 refund must be lower than or equal to the total captured amount of the original PayPal 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.
paymentDescription
(string, optional)		Description of the refund (e.g. Invoice ID) shown to the customer by PayPal in the payment history and in email communication.
Maximum 255 characters.
paymentMethodID
(positiveInt,, required)		Should contain value 400 for the "PayPal Refund" payment method.
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 refunds of a PayPal Deposit, please contact the PXP Financial Account Developer.
originalPaymentID
(guid, required)		The paymentD of the original PayPal Deposit payment (received in the initiatePaymentResponse for initiating a new PayPal payment) must be used as originalPaymentID in the initiatePaymentFromReferenceRequest for creating the refund payment.
shoppingCart
(shoppingCart, optional)		Not yet supported.
Optional.
List of returned items relevant for this refund.
It is possible and recommended by PayPal to transmit the items which are covered with this refund request to reduce customer service contacts.

📘

Remaining authorised amount

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

Example initiatePaymentfromReference for refunding a PayPal Deposit with a partial amount, without the optional ShoppingCart element

<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>PayPalRestAPIProviderTesting</merchantID>
    <shopID>PayPalRestAPIPTShop1</shopID>
    <originalPaymentID>819b1b7a-e499-42d2-9753-09699b240eeb</originalPaymentID>
    <merchantTransactionID>bs-refund-paypal-04032021-pt-29</merchantTransactionID>
   <paymentMethodID>400</paymentMethodID>
   <amount currencyCode="eur">30.20</amount>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>Partial Refund requestäöüß?#</value>
        </data>
    </specificPaymentData>
     <creationTypeID>1</creationTypeID>
</initiatePaymentFromReferenceRequest>

The PayPal payment for which the initiatePaymentFromReference request was sent will remain in state ExecutedByProvider (142). A new payment which is linked to the original PayPal payment will be created.

IDNameSuccessful State
400PayPal RefundRefunded (125)

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

Example initiatePaymentFromReference response for refunding a PayPal payment (partially): 

<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>PayPalRestAPIProviderTesting</merchantID>
        <shopID>PayPalRestAPIPTShop1</shopID>
        <paymentMethod>
            <key>400</key>
            <value>PayPal Refund</value>
        </paymentMethod>
        <merchantTransactionID>bs-refund-paypal-04032021-pt-29</merchantTransactionID>
        <paymentID>a9ddc28a-c0bd-4d7e-8ae5-c49097c7632d</paymentID>
        <userID>8eb5ae57-2d13-4d64-9245-41d583</userID>
        <paymentProvider>
            <key>56</key>
            <value>PayPal</value>
        </paymentProvider>
        <amount currencyCode="EUR">30.20</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>8e5655e1-d9d8-42a8-8076-6c5a77ae1c31</id>
            <definition>
                <key>125</key>
                <value>Refunded</value>
            </definition>
            <createdOn>2021-03-04T19:56:57.3204008Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">30.2</baseAmount>
        <paymentDetails></paymentDetails>
        <paymentAccount>
            <paymentAccountID>3796775f-2fce-49fc-851e-4adf5d001ed3</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentFromReferenceResponse>

Payment State Flow for all PayPal Partial Refund payments:

Option 2: Bulk Refunds for a PayPal Reference or Redirect Pre-Authorisation

This option must be used to send a refund request based on the original PayPal Pre-Authorisation payment using the executePaymentAction API Call with actionID= 114 (“CreateRefund”) and the relevant refund amount.
The amount must be smaller or equal to the (remaining) captured amount (sum of all Paypal Captures minus already made Refunds or Chargebacks).

PXP system will create the refund, identify the Partial Capture payments that are related to this Pre-Authorisation and send the refund requests each by each to PayPal up to the requested refund amount.

📘

Configuration needed

If a merchant wants to take advantage of this PXP feature, this needs to be requested by the Support Team or Account manager.

Errors

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

Error CodeReasonDescription
504Missing fieldNot all required fields necessary for specific payment method have been sent.
e.g. amount or PaymentDescription (mandatory for refunds)
1002Invalid refund amountThere 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])
1003Original payment is refundable / not in a refundable stateRefund not possible
1004Invalid payment methodThe 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.

Updated 7 months ago