GuidesAPI ReferenceDiscussions
Guides

PIX Refund

Suggest Edits

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:

IDNameCredit/Debit State
456PIXRefundDepositedByProvider(29)

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

Supported providers include:

ProviderIDName
195directa24
186Pinbank

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:

DetailDescription
OriginalPaymentIDPaymentiD of the deposit payment
ProviderTransactionIDTransactionID from Pinbank
RefundReceiptData of the refund receipt
ProviderExternalIDID 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.

Error codes Pinbank

The following error codes apply for PIX refund via Pinbank. The description is listed as provided by the provider.

CodeDescriptionState
1Exception errorRefundErrorReportedByProvidder
3Bad requestRefundErrorReportedByProvider
4Blocked userRefundRefusedByProvider
5User not foundRefundRefusedByProvider
7Customer account documentation not approvedRefundRefusedByProvider
15Denied AuthorizationRefundRefusedByProvider
31PIX return not allowedRefundRefusedByProvider
32LpfId not foundRefundRefusedByProvider
33Pix return value not availableRefundRefusedByProvider
36Pix return value not allowedRefundRefusedByProvider
38Pix billet return not allowedRefundRefusedByProvider
56End2End not foundRefundErrorReportedByProvider

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>

Updated 3 days ago