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
438	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 initiatePaymentRequest.specificPaymentData:

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

PIX Refund

Example initiatePaymentFromReferenceRequest (for Pinbank):

  <?xml version="1.0" encoding="utf-8"?>
<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>a9a9be04-1a27-4589-873b-559dac5808bc</originalPaymentID>
	<merchantTransactionID>33d31caf-bb0d-4947-90c7-ebee91fb442c</merchantTransactionID>
	<paymentMethodID>456</paymentMethodID>
	<amount currencyCode="BRL">12.34</amount>
	<specificPaymentData>
		<data xsi:type="keyIntValuePair">
			<key>PaymentProviderID</key>
			<value>186</value>
		</data>
		<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="keyIntValuePair">
		<key>PaymentProviderID</key>
		<value>195</value>
	</data>
	<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 (for Pinbank):

<?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>ceb6e346-4e2b-4330-b613-d59dbe73efda</merchantTransactionID>
		<paymentID>ed33dd97-0ac7-45ad-881b-e1b62ebb49f8</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>f37f4420-d440-4c03-9e13-e34834ebc643</id>
			<definition>
				<key>125</key>
				<value>Refunded</value>
			</definition>
			<createdOn>2024-08-13T14:41:07.5731997Z</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.27</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyIntValuePair">
				<key>OriginalPaymentID</key>
				<value>54046959</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>56qo8jlbzd74yhtg2w3v</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>54046960</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentFromReferenceResponse>

Example initiatePaymentFromReferenceResponse for state RefundRefusedByProvider (for Pinbank):

<?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>

Example initiatePaymentFromReferenceResponse for state RefundErrorOccurred (for Pinbank):

<?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>5d0d5662-b4fd-4a03-be6d-9d9a98b87db3</merchantTransactionID>
		<paymentID>c8441ac6-9ef8-4ced-9a6d-b29c1e67333d</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>9428c24d-c6fe-4c84-a18b-d6b192fbef70</id>
			<definition>
				<key>310</key>
				<value>RefundErrorOccurred</value>
			</definition>
			<createdOn>2024-08-19T15:44:12.8408273Z</createdOn>
			<description>Unexpected response from the provider. Expected 'IdLancamento' in the response.</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>0</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>54133274</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>54133275</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>

Notifications

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(directa24):

<?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 (directa24):

<?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>

Redirect Integration

Backend2BackendIntegration

PIX Refund

📘Flows

Notifications

📘
Flows