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:

ID	Name	Credit/Debit State	Reversal State
88	VISA Refund	Refunded (125)	Cancelled(113)
89	ECMC Refund	Refunded (125)	Cancelled(113)
90	Maestro Refund	Refunded (125)	Cancelled(113)
115	AMEX Refund	Refunded (125)	Cancelled(113)
154	Diners Refund	Refunded (125)	Cancelled(113)
171	AirplusUATPRefund	Refunded (125)	Cancelled(113)
188	JCB Refund	Refunded (125)	Cancelled(113)
190	Discover Refund	Refunded (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 Code	Reason	Description
504	Missing field	Not all required fields necessary for specific payment method have been sent. e.g. amount or PaymentDescription (mandatory for refunds)
1002	Invalid refund amount	There 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])
1003	Original payment is refundable / not in a refundable state	If the original payment has not yet reached `PendingToBeCaptured`or `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.
1004	Invalid payment method	The specified refund payment method ID is not allowed for the original deposit’s payment method.

State Diagram

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>

Backend2Backend Integration

❗️Capture Delay

State Diagram

Notifications

❗️
Capture Delay