PIX Refund

PIX Refund is an option to refund a PIX deposit.

The merchant will initiate the PIX refund with initiatePaymentFromReference call.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
456	PIXRefund	DepositedByProvider(29)

Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).

Supported providers include:

ProviderID	Name
195	directa24
186	Pinbank

Redirect Integration

Currently not supported.

Backend2BackendIntegration

The following parameters can be provided in initiatePaymentFromReferenceRequest.specificPaymentData:

key (value type, required)	value
PaymentDescription (string, optional for Pinbank, required for D24)	Description text (max lenght: 100)

PIX Refund

Example initiatePaymentFromReferenceRequest (for Pinbank):

<initiatePaymentFromReferenceRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<merchantID>B2BTestMerchant</merchantID>
	<shopID>BoletoDepositViaAstropayShop</shopID>
	<originalPaymentID>645174b4-7aa6-4875-abed-e90dbfbf4278</originalPaymentID>
	<merchantTransactionID>TestRefund_19092024_1</merchantTransactionID>
	<paymentMethodID>456</paymentMethodID>
	<amount currencyCode="BRL">10.00</amount>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>My Full Refund Description</value>
		</data>
	</specificPaymentData>
	<creationTypeID>1</creationTypeID>
</initiatePaymentFromReferenceRequest>

Example initiatePaymentFromReferenceRequest (for D24):

<initiatePaymentFromReferenceRequest xmlns:xsd=http://www.w3.org/2001/XMLSchema
                                     xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
                                     xmlns=http://www.cqrpayments.com/PaymentProcessing>
<merchantID>B2BTestMerchant</merchantID>
<shopID>Directa24MockShop</shopID>
<originalPaymentID>2e5b21a7-99a5-4a35-a392-f9bb4996d4c5</originalPaymentID>
<merchantTransactionID>cc1042da-5836-4819-8121-004c8be5dda9</merchantTransactionID>
<paymentMethodID>456</paymentMethodID>
<amount currencyCode="BRL">10.10</amount>
<specificPaymentData>
	<data xsi:type="keyStringValuePair">
		<key>PaymentDescription</key>
		<value>My Full Refund Description</value>
	</data>
</specificPaymentData>
<creationTypeID>1</creationTypeID>
</initiatePaymentFromReferenceRequest>

📘
Flows
For Pinbank the refunds are immediately executed. For D24 please wait for a notification.
For Pinbank the initiatePaymentFromReference response is either Refunded (successful), RefundRefusedByProvider or RefundErrorOccurred. In rare cases it could be RefundCommunicationErrorOccurred.
For D24 the initiatePaymentFromReference response is RefundInitiated (accepted by D24), or RefundRefusedByProvider or InitiateRefundErrorReportedByProvider. In rare cases it could be RefundCommunicationErrorOccurred.
The final state Refunded will be notified to the merchant (for D24 only), alternatively RefundRefusedByProvider.

Example initiatePaymentFromReferenceResponse (successful) for state Refunded (for Pinbank):

<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>B2BTestMerchant</merchantID>
        <shopID>BoletoDepositViaAstropayShop</shopID>
        <paymentMethod>
            <key>456</key>
            <value>PIX Refund</value>
        </paymentMethod>
        <merchantTransactionID>TestRefund_19092024_1</merchantTransactionID>
        <paymentID>020b5e43-0c24-4b53-b8ee-760860dc6c8a</paymentID>
        <userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
        <paymentProvider>
            <key>186</key>
            <value>PINbank</value>
        </paymentProvider>
        <amount currencyCode="BRL">10.00</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>2f6f6a10-e262-4fc3-b15e-c2ab04d7c89c</id>
            <definition>
                <key>125</key>
                <value>Refunded</value>
            </definition>
            <createdOn>2024-09-19T12:21:44.1689733Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>Sucesso.</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">2.65</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyIntValuePair">
                <key>OriginalPaymentID</key>
                <value>54739977</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>3jarh1dwg50kn2le4xco</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>RefundReceipt</key>
                <value>{"pix": {"Data": "13/08/2024", "Hora": "10:50:29", "Valor": 150, "End2EndOriginal": "E60701190202408131345LY5SZVGXC8W", "End2EndDevolucao": "D17079937202408131008D5fa62b95d3"}, "origem": {"Nome": null, "Conta": "2723040", "Agencia": "0600", "CPFCNPJ": "46166590000328", "Instituicao": "PINBANK BRASIL", "InfoEntreUsuarios": ""}, "destino": {"Nome": "JOSE DA SILVA", "Conta": "000605057", "Agencia": "70966", "CPFCNPJ": "29180074839", "TipoConta": "CACC", "Instituicao": "Itau"}}</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>54739983</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentFromReferenceResponse>

The following details are returned in the initiatePaymentFromReferenceResponse on a successful refund with Pinbank:

Detail	Description
OriginalPaymentID	PaymentiD of the deposit payment
ProviderTransactionID	TransactionID from Pinbank
RefundReceipt	Data of the refund receipt
ProviderExternalID	ID send by PXP to provider Pinbank

Example initiatePaymentFromReferenceResponse (Pinbank) with state RefundRefusedByProvider:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>BoletoDepositViaAstropayShop</shopID>
		<paymentMethod>
			<key>456</key>
			<value>PIX Refund</value>
		</paymentMethod>
		<merchantTransactionID>ec58f5bd-16aa-4f94-929b-8d936818f04b</merchantTransactionID>
		<paymentID>5d8da674-46bc-4229-a290-91dae0a030e1</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">12.34</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>549b3fb2-7e57-4db9-8eeb-daa846ff44bc</id>
			<definition>
				<key>309</key>
				<value>RefundRefusedByProvider</value>
			</definition>
			<createdOn>2024-08-19T15:39:14.1570202Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>15</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>Refused.</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">3.27</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyIntValuePair">
				<key>OriginalPaymentID</key>
				<value>54133252</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>7noyzmw8tl3i5u6k1hd2</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>54133253</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentFromReferenceResponse>

<initiatePaymentFromReferenceResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>BoletoDepositViaAstropayShop</shopID>
		<paymentMethod>
			<key>456</key>
			<value>PIX Refund</value>
		</paymentMethod>
		<merchantTransactionID>94687f95-d6d3-42b7-ba0a-62a5d8ee18d1</merchantTransactionID>
		<paymentID>579ab5c7-05f9-4056-9131-67e0bf501c48</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">12.34</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>9cecb9e7-8274-4ea7-b35e-a1c0d28c904f</id>
			<definition>
				<key>309</key>
				<value>RefundRefusedByProvider</value>
			</definition>
			<createdOn>2024-09-19T12:26:06.7254085Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>4</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>BlockedUser</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">3.27</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyIntValuePair">
				<key>OriginalPaymentID</key>
				<value>54739993</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>j4bce5yaoqmxlvsp13ir</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>54739994</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentFromReferenceResponse>

Example initiatePaymentFromReferenceResponse (Pinbak) with state RefundErrorOccurred:

<initiatePaymentFromReferenceResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>BoletoDepositViaAstropayShop</shopID>
		<paymentMethod>
			<key>456</key>
			<value>PIX Refund</value>
		</paymentMethod>
		<merchantTransactionID>9edbbdf2-df22-4208-aa8c-cc0ad1fcdb6a</merchantTransactionID>
		<paymentID>ff0ec397-624a-439f-a93b-b914a21612e5</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">12.34</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>53bfc908-355f-478b-9fed-83d34c412b24</id>
			<definition>
				<key>310</key>
				<value>RefundErrorOccurred</value>
			</definition>
			<createdOn>2024-09-19T12:33:25.8353171Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorResponseCode</key>
					<value>15</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorResponseMessage</key>
					<value>DeniedAuthorization</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">3.27</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyIntValuePair">
				<key>OriginalPaymentID</key>
				<value>54739995</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>vqx9hjcn5si3pdofwb42</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>54739996</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentFromReferenceResponse>

Example initiatePaymentResponse for state RefundInitiated:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema
                                      xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
                                      xmlns=http://www.cqrpayments.com/PaymentProcessing>
<payment
         xsi:type="paymentWithPaymentAccount">
	<merchantID>B2BTestMerchant</merchantID>
	<shopID>Directa24MockShop</shopID>
	<paymentMethod>
		<key>456</key>
		<value>PIX Refund</value>
	</paymentMethod>
	<merchantTransactionID>cc1042da-5836-4819-8121-004c8be5dda9</merchantTransactionID>
	<paymentID>b3aaa53e-9f03-44c9-98c1-84120e53707a</paymentID>
	<userID>ad7d94bc-7c06-4dc8-999e-88b95e</userID>
	<paymentProvider>
		<key>195</key>
		<value>Directa24</value>
	</paymentProvider>
	<amount currencyCode="BRL">10.10</amount>
	<creationType>
		<key>1</key>
		<value>User</value>
	</creationType>
	<userIP>127.0.0.1</userIP>
	<state>
		<id>b1c0987d-26d3-42eb-a8f1-764654229c49</id>
		<definition>
			<key>320</key>
			<value>RefundInitiated</value>
		</definition>
		<createdOn>2024-08-02T14:30:09.2627586Z</createdOn>
		<paymentStateDetails>
			<detail xsi:type="keyStringValuePair">
				<key>PaymentStateReasonID</key>
				<value>1</value>
			</detail>
		</paymentStateDetails>
	</state>
	<isExecuted>false</isExecuted>
	<baseAmount currencyCode="EUR">2.68</baseAmount>
	<paymentDetails>
		<detail xsi:type="keyIntValuePair">
			<key>OriginalPaymentID</key>
			<value>53877167</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderTransactionID</key>
			<value>91356782</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderExternalID</key>
			<value>74090125</value>
		</detail>
	</paymentDetails>
</payment>
</initiatePaymentFromReferenceResponse>

Example initiatePaymentResponse for state InitiateRefusedByProvider (for Pinbank):

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>BoletoDepositViaAstropayShop</shopID>
		<paymentMethod>
			<key>438</key>
			<value>PIX Deposit</value>
		</paymentMethod>
		<merchantTransactionID>98712cd6-91c6-4c74-b9f1-da332de4c6b6</merchantTransactionID>
		<paymentID>d7e8a4a0-0e62-4183-a384-c612492951d6</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">10.00</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>7113c2a3-ca16-4ed1-b150-da1cd37fccb9</id>
			<definition>
				<key>100</key>
				<value>RefusedByProvider</value>
			</definition>
			<createdOn>2023-03-21T12:42:41.0339805Z</createdOn>
			<description>Usuário não encontrado.</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>7</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>Usuário não encontrado.</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">2.65</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>46220141</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentResponse>

Example initiatePaymentResponse for state InitiateRequestProviderCommunicationErrorOccurred (for Pinbank):

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>BoletoDepositViaAstropayShop</shopID>
		<paymentMethod>
			<key>438</key>
			<value>PIX Deposit</value>
		</paymentMethod>
		<merchantTransactionID>c2495d29-09de-4ea4-9cf3-f535ed747332</merchantTransactionID>
		<paymentID>9e6a8d84-cef5-4082-865a-e00b10d19804</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">10.00</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>c3bab67f-ae85-4c9a-8955-c2818b01c035</id>
			<definition>
				<key>325</key>
				<value>InitiateRequestProviderCommunicationErrorOccurred</value>
			</definition>
			<createdOn>2023-03-21T12:58:56.987964Z</createdOn>
			<description>Unexpected response from the provider. Expected 'Message' in the response.</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>3</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">2.65</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>46220146</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentResponse>

Error handling

If a PIX refund with Pinbank goes to RefundCommunicationErrorOccurred / InitiateRequestProviderCommunicationErrorOccurred, PXP will query the status with provider and will update the payment to Refunded or will resend the PIX refund.

📘
Notification for Refunded after Query
When a PIX refund with Pinbank will go to Refunded after communication error state, the state notification will not include a ProviderTransactionID.

Notifications for directa24

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 state Refunded:

<?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>B2BTestMerchant</merchantID>
	<shopID>Directa24MockShop</shopID>
	<paymentMethod>
		<key>456</key>
		<value>PIX Refund</value>
	</paymentMethod>
	<merchantTransactionID>29e5ca24-199f-49a4-8979-df481f360df5</merchantTransactionID>
	<paymentID>eabab02b-e8bf-47c5-a61c-ae013af57f55</paymentID>
	<userID>ad7d94bc-7c06-4dc8-999e-88b95e</userID>
	<paymentProvider>
		<key>195</key>
		<value>Directa24</value>
	</paymentProvider>
	<amount currencyCode="BRL">100.0000</amount>
	<creationType>
		<key>1</key>
		<value>User</value>
	</creationType>
	<userIP>127.0.0.1</userIP>
	<state>
		<id>66bfcb5b-4a53-4390-bb4e-b9c10445671d</id>
		<definition>
			<key>125</key>
			<value>Refunded</value>
		</definition>
		<createdOn>2024-08-02T15:05:48.523</createdOn>
		<paymentStateDetails xsi:nil="true"/>
	</state>
	<isExecuted>true</isExecuted>
	<baseAmount currencyCode="EUR">26.5300</baseAmount>
	<paymentDetails>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderExternalID</key>
			<value>74090173</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderTransactionID</key>
			<value>17642953</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>OriginalPaymentID</key>
			<value>8eb71fa3-eb28-4d05-a337-5a9dd214473b</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>OriginalPaymentMerchantTransactionID</key>
			<value>a53d3841-bc81-4a22-ab0e-2eafd6139ce1</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>OriginalPaymentMethodID</key>
			<value>438</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>OriginalPaymentMethodName</key>
			<value>PIX Deposit</value>
		</detail>
	</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for state RefundRefusedByProvider (Expired):

<?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>B2BTestMerchant</merchantID>
	<shopID>Directa24ProviderShop</shopID>
	<paymentMethod>
		<key>438</key>
		<value>PIX Deposit</value>
	</paymentMethod>
	<merchantTransactionID>hc-20230313-105010</merchantTransactionID>
	<paymentID>45b3be52-5156-458a-bfd3-fe8dc863a110</paymentID>
	<userID>hc20230313105010</userID>
	<paymentProvider>
		<key>195</key>
		<value>Directa24</value>
	</paymentProvider>
	<amount currencyCode="BRL">100.0100</amount>
	<creationType>
		<key>1</key>
		<value>User</value>
	</creationType>
	<userIP>80.121.151.158</userIP>
	<state>
		<id>63214580-b330-4879-aeb3-c94a6bf7d69e</id>
		<definition>
			<key>102</key>
			<value>Expired</value>
		</definition>
		<createdOn>2023-03-13T09:52:23.7</createdOn>
		<paymentStateDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderStatusCode</key>
				<value>EXPIRED</value>
			</detail>
			<detail xsi:type="keyIntValuePair">
				<key>PaymentStateReasonID</key>
				<value>1</value>
			</detail>
		</paymentStateDetails>
	</state>
	<isExecuted>false</isExecuted>
	<baseAmount currencyCode="EUR">26.5300</baseAmount>
	<paymentDetails>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderExternalID</key>
			<value>306</value>
		</detail>
		<detail xsi:type="keyDateTimeValuePair">
			<key>ExpirationDate</key>
			<value>2023-03-13T21:50:11</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderTransactionID</key>
			<value>300819069</value>
		</detail>
	</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for state RefundRefusedByProvider (INVALID_AMOUNT_TO_REFUND):

<?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="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>Directa24MockShop</shopID>
    <paymentMethod>
      <key>456</key>
      <value>PIX Refund</value>
    </paymentMethod>
    <merchantTransactionID>1e9167ae-27d3-41cb-aeca-0e52949e6956</merchantTransactionID>
    <paymentID>3ffd1be5-880f-4e52-9feb-5ea7b12af46e</paymentID>
    <userID>ad7d94bc-7c06-4dc8-999e-88b95e</userID>
    <paymentProvider>
      <key>195</key>
      <value>Directa24</value>
    </paymentProvider>
    <amount currencyCode="BRL">11.0100</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>57eaba55-a87d-40cd-83b4-135bb5e25fbb</id>
      <definition>
        <key>309</key>
        <value>RefundRefusedByProvider</value>
      </definition>
      <createdOn>2025-03-07T12:35:09.827</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>802</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>Amount to refund not valid</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>AdditionalProviderResponseMessage</key>
          <value>INVALID_AMOUNT_TO_REFUND</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">2.9200</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>74240555</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentID</key>
        <value>2ce8e3c5-74ef-4c29-87fa-9322a91549cd</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMerchantTransactionID</key>
        <value>e22220f4-c2a5-4adc-832d-99d23b278cc8</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodID</key>
        <value>438</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName</key>
        <value>PIX Deposit</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for state InitiateRefundErrorReportedByProvider:

<?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="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>Directa24MockShop</shopID>
    <paymentMethod>
      <key>456</key>
      <value>PIX Refund</value>
    </paymentMethod>
    <merchantTransactionID>aaef28cc-cc12-4da2-95f5-a4d82b837be9</merchantTransactionID>
    <paymentID>31c20af9-1c4a-4d38-ab5b-0eac8138ad56</paymentID>
    <userID>ad7d94bc-7c06-4dc8-999e-88b95e</userID>
    <paymentProvider>
      <key>195</key>
      <value>Directa24</value>
    </paymentProvider>
    <amount currencyCode="BRL">11.0200</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>f3799467-8a74-47e7-b7f0-c03b6a96706d</id>
      <definition>
        <key>558</key>
        <value>InitiateRefundErrorReportedByProvider</value>
      </definition>
      <createdOn>2025-03-07T12:29:16.357</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderErrorResponseCode</key>
          <value>208</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderErrorResponseMessage</key>
          <value>Resource not found</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>AdditionalProviderErrorResponseMessage</key>
          <value>RESOURCE_NOT_FOUND</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">2.9200</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>74240553</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentID</key>
        <value>cf70ee27-4723-4d30-a29f-2ec5bb5ac76b</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMerchantTransactionID</key>
        <value>a78f9ccf-68cd-44ea-950c-03492af0cc04</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodID</key>
        <value>438</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName</key>
        <value>PIX Deposit</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for state RefundInitiated

<?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="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>Directa24MockShop</shopID>
    <paymentMethod>
      <key>456</key>
      <value>PIX Refund</value>
    </paymentMethod>
    <merchantTransactionID>3f08906f-e1f1-424d-b692-b1261dca1b42</merchantTransactionID>
    <paymentID>5de4c387-7fd3-4fff-94a3-5ec77f21f27e</paymentID>
    <userID>ad7d94bc-7c06-4dc8-999e-88b95e</userID>
    <paymentProvider>
      <key>195</key>
      <value>Directa24</value>
    </paymentProvider>
    <amount currencyCode="BRL">10.1000</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>2d596273-cdf6-4b0f-af9b-0ad2f96694a0</id>
      <definition>
        <key>320</key>
        <value>RefundInitiated</value>
      </definition>
      <createdOn>2025-03-07T12:25:01.407</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">2.6800</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>74240551</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderTransactionID</key>
        <value>48152763</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentID</key>
        <value>585c6de2-bf75-4e9f-9776-77d28deb4eac</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMerchantTransactionID</key>
        <value>5490b6cc-47c9-48a5-843b-1bfb67d7ed61</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodID</key>
        <value>438</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName</key>
        <value>PIX Deposit</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for state RefundCommunicationErrorOccured##:

<?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="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>Directa24MockShop</shopID>
    <paymentMethod>
      <key>456</key>
      <value>PIX Refund</value>
    </paymentMethod>
    <merchantTransactionID>217f3859-6ce7-4231-9b32-596f58a324be</merchantTransactionID>
    <paymentID>f6eed495-a939-4233-bdb8-e08225c294db</paymentID>
    <userID>ad7d94bc-7c06-4dc8-999e-88b95e</userID>
    <paymentProvider>
      <key>195</key>
      <value>Directa24</value>
    </paymentProvider>
    <amount currencyCode="BRL">11.0100</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>52551e1a-c70b-4c82-aa5c-01779bccee8c</id>
      <definition>
        <key>523</key>
        <value>RefundCommunicationErrorOccured</value>
      </definition>
      <createdOn>2025-03-07T12:38:38.683</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>103</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>X-Date header value out of valid range</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>AdditionalProviderResponseMessage</key>
          <value>INVALID_DATE_RANGE</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">2.9200</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>74240559</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentID</key>
        <value>20bedd4f-b75b-4796-83a8-daf78b7f5509</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMerchantTransactionID</key>
        <value>fcbc8f78-ccba-4a0b-aa3e-b42ef405af03</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodID</key>
        <value>438</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName</key>
        <value>PIX Deposit</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>

Notifications for Pinbank

Notifications for Pinbank are sent for final state. They are especially interesting when the refund goes to a communication error state and the payment is queried on provider side. Depending on the result, it will either be moved to Refunded state or it be will resent to Pinbank.

Example handlePaymentStateChangedNotificationRequest for state Refunded:

<?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="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>BoletoDepositViaAstropayShop</shopID>
    <paymentMethod>
      <key>456</key>
      <value>PIX Refund</value>
    </paymentMethod>
    <merchantTransactionID>f64f3703-fa87-4cda-bbfe-f7409d9cae10</merchantTransactionID>
    <paymentID>b51bdf9a-1638-4d83-a4df-f2cda180915b</paymentID>
    <userID>8a2b9fd3-5a52-4566-8d28-176bc2</userID>
    <paymentProvider>
      <key>186</key>
      <value>PINbank</value>
    </paymentProvider>
    <amount currencyCode="BRL">12.0000</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>3e6b08c8-e962-485c-a3ba-5425e579617b</id>
      <definition>
        <key>125</key>
        <value>Refunded</value>
      </definition>
      <createdOn>2025-03-14T10:17:11.393</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>0</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>Sucesso.</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">3.1800</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>2149333401</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderTransactionID</key>
        <value>8f63tqvgmub54srx9lpj</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentID</key>
        <value>262169bf-8ad2-4cfc-ab56-9c2e6a5f4667</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMerchantTransactionID</key>
        <value>33cee798-268e-4b47-9db6-3e8167c09203</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodID</key>
        <value>438</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>OriginalPaymentMethodName</key>
        <value>PIX Deposit</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>

PIX Refund

Redirect Integration

Backend2BackendIntegration

PIX Refund

📘
Flows

Error handling

📘
Notification for Refunded after Query

Notifications for directa24

Notifications for Pinbank

Redirect Integration

Backend2BackendIntegration

PIX Refund

📘Flows

Error handling

📘Notification for Refunded after Query

Notifications for directa24

Notifications for Pinbank

📘
Flows

📘
Notification for Refunded after Query