PIX Deposit

PIX Deposit is a payment method to offer the popular PIX deposit option to customers in Brazil.

In below flow, PXP returns a QR code that the merchant will display on his website. The user needs to access his banking app, select to pay with PIX and scan the QR code or copy and paste the code provided. After that the banking app will show the PIX payment as completed.

The user will also see a payment confirmation in the banking app.

The QR code is applicable only for a single payment. The payment will be denied in the banking app when the expiration time is reached.

The expiration time (for Directa24/D24) is 3 hours.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
438	PIX Deposit	DepositedByProvider(29)

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

Supported providers include:

ProviderID	Name
195	directa24
186	Pinbank

Payment flow

Redirect Integration

Currently not supported.

Backend2BackendIntegration

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, required)	value
PaymentProviderID (string, optional)	Always 105
PaymentDescription (string, optional for directa24, required for Pinbank)	Description text (max lenght: 100)

User details

An existing or new user has to have the following details:

User details
Firstname (string, required for directa24)	The user`s first name.
Lastname (string, required for directa24)	The user`s last name.
email (string, required for directa24)	The user`s email address.
address including telephoneNumber (string, optional)	The user`s address including telephoneNumber is optional.
identificationNumber (string, required for directa24 and PINbank)	The user`s CPF number.

❗️
Identification Number
The customer's CPF number needs to be present at the field IdentificationNumber for the user provided in the request. If a new user is being created or the identificationNumber is not already present on the user, you need to send a initiatePaymentRequest.userData data element within the initiation request to update the existing user.
For CPF Generator see here, for CPF Validator.

PIX Deposits

Example initiatePaymentRequest (for directa24):

<initiatePaymentRequest xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=http://www.w3.org/2001/XMLSchema>
    <merchantID>{{merchant}}</merchantID>
    <shopID>{{shop}}</shopID>
    <merchantTransactionID>{{merchantTransactionID}}</merchantTransactionID>
    <paymentMethodID>438</paymentMethodID>
    <amount currencyCode="BRL">100.01</amount>
    <userID>{{newUserID}}</userID>
    <userData>
        <username>{{newUserName}}</username>
        <firstname>John</firstname>
        <lastname>Doe</lastname>
        <currencyCode>BRL</currencyCode>
        <languageCode>EN</languageCode>
        <email>{{newUserEmail}}</email>
        <address>
            <street>Rua Eça de Queirós</street>
            <houseNumber>1b</houseNumber>
            <postalCode>89812-580</postalCode>
            <city>Chapecó</city>
            <state>SC</state>
            <countryCode2>BR</countryCode2>
            <telephoneNumber>55493034-5962</telephoneNumber>
        </address>
        <dateOfBirth>1980-10-10T00:00:00</dateOfBirth>
        <gender>Male</gender>
        <identificationNumber>84932568207</identificationNumber>
    </userData>
    <userIP>80.121.151.158</userIP>
    <userSessionID>t02d03hwaxkrl5gmabcypwmm</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>provider testing</value>
        </data>
    </specificPaymentData>
</initiatePaymentRequest>

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest 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>
	<merchantTransactionID>ccede875-00f7-4e4f-8c8d-bce375eae60e002</merchantTransactionID>
	<paymentMethodID>438</paymentMethodID>
	<amount currencyCode="BRL">0.01</amount>
	<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
	<userData>
		<username>01351ef4-3bb4-8888-bf35-aabd7200db96</username>
		<firstname xsi:nil="true" />
		<lastname xsi:nil="true" />
		<currencyCode xsi:nil="true" />
		<languageCode xsi:nil="true" />
		<email xsi:nil="true" />
		<address xsi:nil="true" />
		<gender>Male</gender>
		<identificationNumber>00050792508106</identificationNumber>
		<identificationNumberType xsi:nil="true" />
		<drivingLicenseNumber xsi:nil="true" />
		<drivingLicenseIssuingState xsi:nil="true" />
		<globalUserID xsi:nil="true" />
	</userData>
	<userIP>127.0.0.1</userIP>
	<userSessionID>97421760-d33b-40e9-b757-65e930224714</userSessionID>
	<creationTypeID>1</creationTypeID>
	<specificPaymentData>
		<data xsi:type="keyIntValuePair">
			<key>PaymentProviderID</key>
			<value>186</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>Some description</value>
		</data>
	</specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse for directa24:

<initiatePaymentResponse 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>Directa24ProviderShop</shopID>
        <paymentMethod>
            <key>438</key>
            <value>PIX Deposit</value>
        </paymentMethod>
        <merchantTransactionID>hc-20230309-124529</merchantTransactionID>
        <paymentID>4286d74e-28f4-498c-8f00-5ba169b2bb46</paymentID>
        <userID>hc20230309124529</userID>
        <paymentProvider>
            <key>195</key>
            <value>Directa24</value>
        </paymentProvider>
        <amount currencyCode="BRL">100.01</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>8bd18b38-7bd7-42a3-afac-76a2717e1399</id>
            <definition>
                <key>3</key>
                <value>InitiatedByProvider</value>
            </definition>
            <createdOn>2023-03-09T11:45:32.6866187Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">26.53</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>300818074</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ExpirationDate</key>
                <value>2023-03-09 23:45:30</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>TextToQRCode</key>
                <value>00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/6d3ddf074690468eb8ddd181208cf0965204000053039865802BR5925V R Andromeda Servicos Di6008Curitiba62070503***6304A8E1</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>BankReference</key>
                <value>56697954</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>Base64QRCode</key>
                <value>data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACNElEQVR4Xt3UsdmkIBAGYEikBUmktTWBFjRBSLQFSKA1SaAFSOA43f+/Z4Vt4AjfwJlhPgTl80TwX0EEE7P+RQe+CtiFVBSlAIegpU19kIa+JrosxCn8BRQKAmZysq9g94mDEcXtGxS1UGKPoMhvH58QAdbv8zPLA+oxs7UCh+P3Pj4hQikWANARF8r6sGV0FLEgF8zWhZSJdgYeLo/0vsInROLBduQ11ktYu1Ck1Kk2vc+y2C7EkWLPp7nWVHdjT8izghkmHY59011I9VvHEapY+V7lA+JsU8SCDziZaw0t0FkgT1cxB3P30QCUGWmFT1BD1YWMPDIsiIUPoA+RggUJwDzW5Wq9gRKZrDv0gLMj9EHV65sAmLUCV+sNJBdJyUQqOserbAMRar8KbPdV6ruPJyQZ2b7ZGloXr/EbKAKG4MRA4givS24g7Xxg7sQ6c35H6glxBGuSOrMTyruPJ5RwTixDBeh2r6GB+rIo02otWqp7uCeUcqJgixQvfi+qgbzVyRXnFDB3lW2gvlK8c2im7R2HBlJSlCTr/Ajvsg1kFJwsHuo88fkL1EcskBnAe/wG4up0yCMY+WxQFzJHYsF1Rwoe1xpaQC79Tfa4GnqtoYFI9mEVYBrmE97P9Ak1l2uNg/gXhyfU35ZzEZvXAvVVtoFUrNo8EXP+yWkDNY1JChKkuMv2YKeceFxDfj2PDqjphWQdcp9IH4pCpf4pFAvm3ccDYv2DJ5lJSH6TXfg8/zf8AQachsG9crzdAAAAAElFTkSuQmCC</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>105</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Example initiatePaymentRequest for PINbank:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest 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>
	<merchantTransactionID>be6553ca-ccae-4917-9065-7e30222c469f</merchantTransactionID>
	<paymentMethodID>438</paymentMethodID>
	<amount currencyCode="BRL">0.01</amount>
	<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
	<userData>
		<username>01351ef4-3bb4-8888-bf35-aabd7200db96</username>
		<firstname xsi:nil="true" />
		<lastname xsi:nil="true" />
		<currencyCode xsi:nil="true" />
		<languageCode xsi:nil="true" />
		<email xsi:nil="true" />
		<address xsi:nil="true" />
		<identificationNumber>00050792508106</identificationNumber>
		<identificationNumberType xsi:nil="true" />
		<drivingLicenseNumber xsi:nil="true" />
		<drivingLicenseIssuingState xsi:nil="true" />
		<globalUserID xsi:nil="true" />
		<nationality xsi:nil="true" />
		<identificationIssuingCountry xsi:nil="true" />
	</userData>
	<userIP>127.0.0.1</userIP>
	<userSessionID>adcaa126-ba55-4e77-af87-181c7f26c146</userSessionID>
	<creationTypeID>1</creationTypeID>
	<specificPaymentData>
		<data xsi:type="keyIntValuePair">
			<key>PaymentProviderID</key>
			<value>186</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>Some description</value>
		</data>
	</specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse for PINbank:

<initiatePaymentResponse 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>438</key>
            <value>PIX Deposit</value>
        </paymentMethod>
        <merchantTransactionID>ccede875-00f7-4e4f-8c8d-bce375eae60e002</merchantTransactionID>
        <paymentID>a026b44b-5148-43f0-8148-de0d37f6cfb1</paymentID>
        <userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
        <paymentProvider>
            <key>186</key>
            <value>PINbank</value>
        </paymentProvider>
        <amount currencyCode="BRL">0.01</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>a0ce71e4-934c-445f-ad6d-8fa4878e8ca5</id>
            <definition>
                <key>3</key>
                <value>InitiatedByProvider</value>
            </definition>
            <createdOn>2023-03-15T14:14:41.2504662Z</createdOn>
            <description>https://dev.pinbank.com.br/checkout/Transferencia/ConfirmacaoBanco/T=XJqnDcASwCiQfxMbuEYGBk7VKOra4IF01lPvzg</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>Sucesso.</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectUrl</key>
                    <value>https://dev.pinbank.com.br/checkout/Transferencia/ConfirmacaoBanco/T=XJqnDcASwCiQfxMbuEYGBk7VKOra4IF01lPvzg</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">0</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>3269841753674598</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>TextToQRCode</key>
                <value>TEST</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>BankReference</key>
                <value>5968371422857936</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>Base64QRCode</key>
                <value>VEVTVA==</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>46151054</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Fields returned in the response:

Field name	Description
ProviderTransactionID	Reference at directa24 resp. at Pinbank.
ExpirationDate	Expiration date and time. Returned only for directa24 For directa24 (D24) the expiration time is 3 hours resp. 4 hours to cover bank approval times. For Pinbank the expiration time is 24 hours.
TextToQRCode	Plain text string line ("digitable line") the user can use to manually pay for the PIX instead of scanning the QR. Make sure the user can't see the QR code after the expiration_date was reached. On mobile devices, the user must copy the digitable line and manually paste it into their banking app. It is advisable to display a copy button next to the digitable line in the merchant´s cashier, so that the digitable line is copied into the user`s clipboard.
BankReference	Reference from the bank. For directa24 (D24) this is an internal reference that may sometimes be passed to the bank, but it will not appear on the user´s bank acount statement.
Base64QRCode	PNG image encoded in base64. You can use the following HTML tag to render the QR code on your website: `<img src='qr_code'/>`
ProviderExternalID	PXP´s ID that was sent to directa24 respectively to Pinbank.

📘
Error states
Relevant error cases for the merchant include:
InitiateRefusedByProvider
RefusedByProvider

Example initiatePaymentResponse for state InitiateErrorReportedByProvider (for directa24):

Here an incorrect _currency _was sent in the initiatePayment Request - JPY instead of BRL. The error InitiateErrorReportedByProvider indicates an incorrect configuration. This error should appear only during the payment method setup.

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>Directa24ProviderShop</shopID>
    <merchantTransactionID>OB-20230307-0108</merchantTransactionID>
    <paymentMethodID>438</paymentMethodID>
    <amount currencyCode="JPY">100</amount>
    <userID>OB-20230307-0101</userID>
    <userData>
        <username>testuser</username>
        <firstname>Test</firstname>
        <lastname>User</lastname>
        <currencyCode>BRL</currencyCode>
        <email>[email protected]</email>
        <address>
           <street>Rua Eça de Queirós 1b</street>
            <postalCode>89812-580</postalCode>
            <city>Chapecó</city>
            <state>SC</state>
            <countryCode2>BR</countryCode2>
            <telephoneNumber>55493034-5962</telephoneNumber>
        </address>
        <gender>Male</gender>
        <identificationNumber>84932568207</identificationNumber>
    </userData>
    <userIP>127.0.0.22</userIP>
    <userSessionID>08b980b9-b5be-4d0a-9e1b-a6541d6ac9ce</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>paymentDescription</key>
            <value>test</value>
        </data>
    </specificPaymentData>
</initiatePaymentRequest>

<initiatePaymentResponse 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>Directa24ProviderShop</shopID>
        <paymentMethod>
            <key>438</key>
            <value>PIX Deposit</value>
        </paymentMethod>
        <merchantTransactionID>OB-20230307-0108</merchantTransactionID>
        <paymentID>fd8ba16b-bd5b-4dbe-9c7c-93de28135f0f</paymentID>
        <userID>OB-20230307-0101</userID>
        <paymentProvider>
            <key>195</key>
            <value>Directa24</value>
        </paymentProvider>
        <amount currencyCode="JPY">100</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.22</userIP>
        <state>
            <id>189e358c-7bae-4e56-8d6e-26b156616c7d</id>
            <definition>
                <key>4</key>
                <value>InitiateErrorReportedByProvider</value>
            </definition>
            <createdOn>2023-03-15T14:33:29.5104906Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderErrorResponseCode</key>
                    <value>201</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderErrorResponseMessage</key>
                    <value>Currency JPY not allowed for Country BR</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">0.77</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>427</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Example initiatePaymentResponse for state InitiateErrorReportedByProvider (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>60a57b2e-c9ef-4cfe-aec7-c300e7e36e62</merchantTransactionID>
		<paymentID>ae67bc6c-d453-4252-ab99-5c18e6152698</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>1165b6d6-038a-42d8-adae-a6f6d0822b27</id>
			<definition>
				<key>4</key>
				<value>InitiateErrorReportedByProvider</value>
			</definition>
			<createdOn>2023-03-21T12:54:48.9562159Z</createdOn>
			<description>Unexpected Message</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorResponseCode</key>
					<value>12</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorResponseMessage</key>
					<value>Unexpected Message</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>46220144</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentResponse>

Example initiatePaymentResponse for state InitiateRefusedByProvider (for directa24):

The error InitiateRefusedByProvider indicates incorrect data sent by the merchant in the initiatePaymentRequest, e.g. an incorrect *identificationNumber**:

Error details are stored and returned in the fields ProviderResponseCode and ProviderResponseMessage.

<initiatePaymentResponse 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>Directa24ProviderShop</shopID>
        <paymentMethod>
            <key>438</key>
            <value>PIX Deposit</value>
        </paymentMethod>
        <merchantTransactionID>OB-20230307-01082</merchantTransactionID>
        <paymentID>7a25672f-17c8-4e19-b153-ed1589762666</paymentID>
        <userID>OB-20230307-0101</userID>
        <paymentProvider>
            <key>195</key>
            <value>Directa24</value>
        </paymentProvider>
        <amount currencyCode="BRL">10.02</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.22</userIP>
        <state>
            <id>9a4ca57b-d4c4-4a27-b7b7-880eb3745ee4</id>
            <definition>
                <key>550</key>
                <value>InitiateRefusedByProvider</value>
            </definition>
            <createdOn>2023-03-27T09:10:30.6238675Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>400</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>Invalid amount. The minimum is USD 2 or equivalent in local currency</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">2.66</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>704</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

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 (notification without bank account data and failure 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 a successful payment (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-104608</merchantTransactionID>
	<paymentID>baf43537-1f33-4a6e-b343-5289a0179ff3</paymentID>
	<userID>hc20230313104608</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>7369d6ab-1522-4f2a-9bf7-7f0019f7582c</id>
		<definition>
			<key>29</key>
			<value>DepositedByProvider</value>
		</definition>
		<createdOn>2023-03-13T09:47:06.123</createdOn>
		<paymentStateDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderStatusCode</key>
				<value>COMPLETED</value>
			</detail>
		</paymentStateDetails>
	</state>
	<isExecuted>true</isExecuted>
	<baseAmount currencyCode="EUR">26.5300</baseAmount>
	<paymentDetails>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderExternalID</key>
			<value>305</value>
		</detail>
		<detail xsi:type="keyDateTimeValuePair">
			<key>ExpirationDate</key>
			<value>2023-03-13T21:46:11</value>
		</detail>
		<detail xsi:type="keyStringValuePair">
			<key>ProviderTransactionID</key>
			<value>300819066</value>
		</detail>
	</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for an expired payment (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>

Example handlePaymentStateChangedNotificationRequest for a successful payment (Pinbank):

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest 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>387c564b-4e82-432c-ab5e-333f53171c9c</merchantTransactionID>
		<paymentID>c31a8a84-862b-4deb-a185-dface854a631</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">10.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>6a58d34d-a883-4dc7-a4b1-3d5bdc55a280</id>
			<definition>
				<key>29</key>
				<value>DepositedByProvider</value>
			</definition>
			<createdOn>2023-03-21T13:06:06.623</createdOn>
			<paymentStateDetails xsi:nil="true" />
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">2.6500</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>46220149</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>4697185326279485</value>
			</detail>
		</paymentDetails>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for an expired payment (Pinbank):

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest 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>fcdb9a38-a154-4a22-ace7-05359019ef28</merchantTransactionID>
		<paymentID>0a4f44e0-feee-4b4c-866f-3f1a51a8aaee</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">10.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>8990698f-da2d-44d5-87cf-3888a854b9a2</id>
			<definition>
				<key>102</key>
				<value>Expired</value>
			</definition>
			<createdOn>2023-03-21T13:03:42.453</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyIntValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">2.6500</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>46220148</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>3419756288693174</value>
			</detail>
		</paymentDetails>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Notifications (with bank account data)

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

The updated flow with bank account data is available for both Pinbank and D24/OKP.

The following bank account details will be notified:

Field name	Description	Pinbank	D24
accountNumber	Bank account number ("Conta Pagador")	Yes	Yes
bankCode	Bank code ("Codigo Banco Pagador")	Yes	No
accountOwner	Bank account owner ("Nome Pagador")	Yes	Added by PXP
bankName	Bank name ("Banco Pagador")	Yes	Yes
bankSortCode	Bank´s ISPB code ("Isbp Banco Pagador")	Yes	Yes
branchCode	Bank branch code ("Agencia Pagador")	Yes	Yes
accountType	Bank account type ("Tipo Conta"), e.g. "CACC"	Yes	Yes

The following logic is applied concerning the ISPB value:

📘
ISPB handling
PXP is hosting a list with the mapping between ISPB and bank code. The list is updated manually, based on the data from BCB (Central Bank of Brazil).

If PXP can map the ISPB to a bank code, then
the found bank code will be stored in the bankCode field on the bank account.
the ISPB will be stored in the bankSortCode field on the bank account.

If PXP cannot map the ISPB to a bank code, then
the ISPB will be stored in both the bankCode and bankSortCode field.
PXP will then check and update the mapping between ISPB and bank code.

Example handlePaymentStateChangedNotificationRequest for a successful payment (Pinbank; with bank account information):

<handlePaymentStateChangedNotificationRequest 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>8cd1a610-7f29-4e60-8f6a-03dbf0ad4cab</merchantTransactionID>
		<paymentID>2c2e862c-3264-4cbc-a83f-c5b744b2ca7c</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">10.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>d4dbb5b7-dab2-4d12-b15a-3520b369da96</id>
			<definition>
				<key>29</key>
				<value>DepositedByProvider</value>
			</definition>
			<createdOn>2024-09-24T11:55:33.84</createdOn>
			<paymentStateDetails xsi:nil="true"/>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">2.6500</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>54812305</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>2179458632957648</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ReferenceID</key>
				<value>3671925841258469</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderGUID</key>
				<value>E22896431202407081553aaHx3RApV7L</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>4eb903fe-7b33-4040-8847-0e47ff5adcad</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>accountNumber</key>
					<value>123456</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>bankCode</key>
					<value>380</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>accountOwner</key>
					<value>TESTE</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>bankName</key>
					<value>PICPAY</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>bankSortCode</key>
					<value>22896431</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>branchCode</key>
					<value>01234</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountType</key>
					<value>CACC</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

PIX Deposit with Mock - Pinbank

In order to test the notification with bank account details for Pinbank, do the following:

Create a PIX deposit with Pinbank on the test environment (test1).
Open the mock page
Leave the MID field as it is.
Enter the ProviderTransactionID from the initiatePaymentResponse into the field NSUPinbank
Enter the ReferenceID from the initiatePaymentResponse into the field PinbankQrCodeId
Enter the amount in decimal places in ValorPago and ValorOriginal
Change the other fields if necessary (NomeBanco - bank name; ISPB, Agencia (branch code), Conta (bank account number), Nome Pagador (bank account holder), CPFPagador (CPF of the payer), TipoConta (bank account type), CodigoBanco (bank code), EndToEnd (EndToEndID)
Click Submit Notification
The payment will go to DepositedByProvider state and a notification with bank details will be sent.

PIX Deposit with Mock - D24

In order to test the notification with bank account details for D24/OneKeyPayments, do the following:

Create a PIX deposit with Directa24 on the test environment (test1).
Make sure to include an identificationNumber as "12345678901".
They payment will go directly to DepositedByProvider state and a notification with the bank details will be sent.

PIX Deposit

Payment flow

Redirect Integration

Backend2BackendIntegration

User details

❗️
Identification Number

PIX Deposits

📘
Error states

Notifications (notification without bank account data and failure notifications)

Notifications (with bank account data)

📘
ISPB handling

PIX Deposit with Mock - Pinbank

PIX Deposit with Mock - D24

Payment flow

Redirect Integration

Backend2BackendIntegration

User details

❗️Identification Number

PIX Deposits

📘Error states

Notifications (notification without bank account data and failure notifications)

Notifications (with bank account data)

📘ISPB handling

PIX Deposit with Mock - Pinbank

PIX Deposit with Mock - D24

❗️
Identification Number

📘
Error states

📘
ISPB handling