GuidesAPI ReferenceDiscussions
Guides

Refund for PayPal Deposit

Suggest Edits

🚧

This page is about the V2 integration

For information on PayPalExpressCheckoutDeposit see here.


Introduction

PayPal refunds should be used by the merchant to initiate a refund for the already made deposits and captured payments.

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.

This chapter describes sending PayPal Refund requests for the following payment methods:

  • PayPal Reference Deposit (393)
  • PayPal Redirect Deposit (394)

To initiate a refund for a PayPal Reference Deposit or PayPal Redirect Deposit, the initiatePaymentFromReference API call must be used.

The paymentID of the original PayPal payment (received in the initiatePaymentResponse for initiating a new PayPal payment) must be used as originalPaymentID in the initiatePaymentFromReferenceRequest for creating the refund.

To support PayPal Refund functionality, PXP Financial offers the following payment method:

IDName
400PayPal Refund

📘

Capture payments must be in state DepositedByProvider

Refunds can only be done for PayPal payments which were already captured with provider PayPal (Capture payments must be in state DepositedByProvider).

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

Field (value type, required)Description
originalPaymentIDThe PaymentID received in the initiatePaymentResponse for initiating a new PayPal payment
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.

📘

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

<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>{{merchant}}</merchantID>
    <shopID>{{shop}}</shopID>
    <originalPaymentID>96096d9f-3fbb-4f85-9be6-7a8f22c0a125</originalPaymentID>
    <merchantTransactionID>{{refundMerchantTransactionID}}</merchantTransactionID>
    <paymentMethodID>400</paymentMethodID>
    <amount currencyCode="eur">2.00</amount>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>My refund payment</value>
        </data>
    </specificPaymentData>
    <creationTypeID>3</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>hc-refund-20211011-124805</merchantTransactionID>
        <paymentID>b55be21d-f14c-471a-9912-713b103f9bf8</paymentID>
        <userID>hc_20211008_011900</userID>
        <paymentProvider>
            <key>56</key>
            <value>PayPal</value>
        </paymentProvider>
        <amount currencyCode="EUR">2.00</amount>
        <creationType>
            <key>3</key>
            <value>Api</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>9b91e1f4-6a43-477f-93d2-093e025d4486</id>
            <definition>
                <key>125</key>
                <value>Refunded</value>
            </definition>
            <createdOn>2021-10-11T10:48:07.6037081Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">2</baseAmount>
        <paymentDetails></paymentDetails>
        <paymentAccount>
            <paymentAccountID>8ba2ddcb-af71-4a37-8ce4-b8014f03ade0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentFromReferenceResponse>

Payment State Flow for all PayPal Partial Refund payments:

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.

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

It is possible, that Paypal Refunds are created by an operator via the PXP Admin or the Paypal account. In this case, the PXP system

  • creates the refund
  • notifies the merchant (The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification. )

Example handlePaymentStateChangedNotificationRequest for a refund of a PayPal payment, if it was created via PXP Admin or Paypal Account and not via the merchant system:

<?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>SkipDetailPageShop<shopID>
    <paymentMethod>
      <key>400<key>
      <value>PayPal Refund<value>
    <paymentMethod>
    <merchantTransactionID>0PM84269U1704734E<merchantTransactionID>
    <paymentID>3160ef94-a333-47dc-961d-5d49c038e03d<paymentID>
    <userID>hc_20220329_181557<userID>
    <paymentProvider>
      <key>56<key>
      <value>PayPal<value>
    <paymentProvider>
    <amount currencyCode="EUR">11.0000<amount>
    <creationType>
      <key>6<key>
      <value>Provider<value>
    <creationType>
    <userIP>10.155.19.252<userIP>
    <state>
      <id>db0b5529-611a-4105-8d1a-f76f2fc47ccb<id>
      <definition>
        <key>125<key>
        <value>Refunded<value>
      <definition>
      <createdOn>2022-03-29T16:19:16.347<createdOn>
      <paymentStateDetails xsi:nil="true" />
    <state>
    <isExecuted>true<isExecuted>
    <baseAmount currencyCode="EUR">11.0000<baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID<key>
        <value>40901039<value>
      <detail>
      <detail xsi:type="keyIntValuePair">
        <key>OriginalPaymentID<key>
        <value>40901038<value>
      <detail>
    <paymentDetails>
    <paymentAccount>
      <paymentAccountID>17ce602e-b2cd-46da-8427-39023292583a<paymentAccountID>
    <paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>

How to create PayPal Refunds manually

Create a PayPal Refund via PSA

It is also possible to initiate a PayPal refund via PXP Payment Service Admin tool.

Create a PayPal Refund via the merchants PayPal Account.

It is also possible to initiate a PayPal refund via the merchant PayPal account.

How to test PayPal Refunds

  • Test-Cases applicable for PayPal Refunds:
    Test Scenarios can be found here: PayPal Test Cases
  • Information how to manipulate a PayPal capture payment for testing purposes using the PXP Admin tool:

Updated 8 months ago