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.
Updated 7 days ago