Card Refunds

Card Refund is a standalone transaction which is linked to an original card deposit transaction. In order to trigger a Refund, the original card deposit should be in PendingToBeCaptured (306) or CapturedByProvider (27) state. The amount of the refund transaction can be up to the amount to the original transaction (partial vs. full refunds).

Refunds can be triggered only with the Backend2Backend Integration.

The following method IDs are covered in this section:

IDNameCredit/Debit StateReversal State
88VISA RefundRefunded (125)Cancelled(113)
89ECMC RefundRefunded (125)Cancelled(113)
90Maestro RefundRefunded (125)Cancelled(113)
115AMEX RefundRefunded (125)Cancelled(113)
154Diners RefundRefunded (125)Cancelled(113)
171AirplusUATPRefundRefunded (125)Cancelled(113)
188JCB RefundRefunded (125)Cancelled(113)
190Discover RefundRefunded (125)Cancelled(113)

Payment method interaction type: Synchronous Execution (see Interaction Types).

Backend2Backend Integration

For triggering a card deposit refund the initiatePaymentFromReferenceRequest should be invoked.

In the field initiatePaymentFromReferenceRequest.paymentMethodID the specific payment method ID from the above table should be provided.

The field initiatePaymentFromReferenceRequest.amount should contain the amount to be refund to the customer credit card. Partial refunds are possible.

The following key-value pair should be placed in initiatePaymentFromReferenceRequest.specificPaymentData:

  • key = PaymentDescription
  • value = Your reason for the refund

Example initiatePaymentFromReferenceRequest for Card Refund:

<?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>20141211_11</merchantTransactionID>
    <paymentMethodID>88</paymentMethodID>
    <amount currencyCode="EUR">10</amount>
    <specificPaymentData>               
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>Your reason for refund</value>
        </data>
    </specificPaymentData>
</initiatePaymentFromReferenceRequest>

Example initiatePaymentFromReferenceResponse for Card Refund:

<?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>88</key>
            <value>VISA Refund</value>
        </paymentMethod>
        <merchantTransactionID>20141211_1</merchantTransactionID>
        <paymentID>7facb804-6ee0-4a0e-9df9-55e7f8233dac</paymentID>
        <userID>KalxiaTestUser_3</userID>
        <paymentProvider>
            <key>92</key>
            <value>CQRUK</value>
        </paymentProvider>
        <amount currencyCode="GBP">30</amount>
        <creationType>
            <key>2</key>
            <value>MerchantOperator</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 xsi:nil="true"/>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">37.89</baseAmount>
        <paymentDetails xsi:nil="true"/>
        <paymentAccount>
            <paymentAccountID>c8650e17-89ff-4566-a4de-835d8818b3f3</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentFromReferenceResponse>

The creationType will be automatically set to MerchantOperator (2).
The field initiatePaymentFromReferenceResponse.payment.state.definition will have the key-value 306 PendingToBeCaptured if the refund was accepted (authorised successfully by the schemes).

❗️

Capture Delay

In certain situations the requested refund has to be manually approved by an operator of PXP or a merchant operator before it is captured.

In that case, the initiatePaymentFromReferenceResponse.payment.state.definition field will have the key-value 320 RefundInitiated (instead of PendingToBeCaptured).

Only when the operator approves the refund later on, the state of the refund payment will change to PendingToBeCaptured and the refund will be cleared with the schemes.

If a refund cannot be created 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 stateIf the original payment has not yet reached PendingToBeCapturedor CapturedByProvider, the refund is not possible.
On the other hand, the original payment could have already reached a state that is not refundable anymore. For that case this error code can be returned as well.
1004Invalid payment methodThe specified refund payment method ID is not allowed for the original deposit’s payment method.

State Diagram

891

Notifications

A refund payment which is in state PendingToBeCaptured will be sent by PXP for clearing with the schemes at the next possible point of time. When this was done successfully, the state of the state will change to Refunded (key-value 125).

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 ECMC Refund in Refunded state:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest
    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>89</key>
            <value>ECMC Refund</value>
        </paymentMethod>
        <merchantTransactionID>20141215_4</merchantTransactionID>
        <paymentID>f1147803-edb4-48f1-a9dd-ac595e1341b9</paymentID>
        <userID>KalxiaTestUser_5</userID>
        <paymentProvider>
            <key>92</key>
            <value>CQRUK</value>
        </paymentProvider>
        <amount currencyCode="EUR">30.0000</amount>
        <creationType>
            <key>2</key>
            <value>MerchantOperator</value>
        </creationType>
        <userIP>195.72.132.1</userIP>
        <state>
            <id>d08ff23f-1374-47b6-ae92-ee4655f7911c</id>
            <definition>
                <key>125</key>
                <value>Refunded</value>
            </definition>
            <createdOn>2014-12-15T11:39:22.867</createdOn>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">30.0000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>207764</value>
            </detail>
            <detail xsi:type="keyIntValuePair">
                <key>ParentPaymentCreationTypeID</key>
                <value>1</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>AuthorizationSequenceValue</key>
                <value>095355</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>906004724</paymentAccountID>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>